TolstoySDK package). It also says what Tolstoy measures and what it does not, so that you can tell your client before you start.
This page as Markdown: https://developers.gotolstoy.com/agents/ecommerce-analytics.md. All pages: https://developers.gotolstoy.com/llms.txt.
If you are a person, give your agent this prompt:
What you get
Your storefront code sends events with the E-commerce Analytics SDK, for exampleproduct_view, add_to_cart or checkout_started. You choose the names. For any period of whole UTC days, up to 180 days, the Tolstoy store analytics report gives each event name with two numbers:
events: how many times the event was sent.shoppers: how many different shoppers sent it. The SDK keeps one shopper ID per browser, so one person on two devices counts as two shoppers.
What you do not get
- No conversion rate, funnel or revenue for your events, and no orders beyond the count of an order event that you send yourself. The report counts each event name on its own, and it does not link your events to orders.
- No numbers by parameter. Tolstoy keeps the parameters of each event, but the report does not show them or group by them.
- No numbers for today. The report covers whole UTC days before today. Events that you send today show in the report from about 06:30 UTC tomorrow.
- No daily series. For the counts of one day, ask for a period of that one day.
- No server SDK. The SDK runs in the browser, on the storefront page. It has no call that identifies a shopper by email or account.
- Up to 120 event names in one report, the most frequent first. The list also holds the events of Tolstoy widgets, if the store has any.
What needs a browser
Two steps run on Tolstoy pages in a browser, not through an API:- Sign-up. It uses a Google account, or an email address and a password with a 6-digit code that Tolstoy sends to that address. You need a browser and access to that inbox.
- The approval of the sign-in of the Tolstoy CLI or the Tolstoy MCP, on the page that the sign-in opens.
1. Create the account and sign in
With the Tolstoy CLI:tolstoy auth signup opens the Tolstoy sign-up page in the browser, and prints its link in case the browser does not open. After sign-up, the browser goes to the CLI sign-in page. Click Sign in there, and the CLI saves its key. If the account already exists, run tolstoy auth login instead. tolstoy auth status shows the account, app key and store that the CLI uses.
With the Tolstoy MCP, sign up at https://platform.gotolstoy.com/signup. Then add the server https://apilb.gotolstoy.com/mcp/v1/mcp to your MCP client, and sign in to Tolstoy when the client asks. Connect your agent has the command for each client.
2. Get the app key
The app key identifies the Tolstoy workspace. It is not a secret: it is in the code of every page that sends events.- With the CLI, copy the
App key:value printed bytolstoy auth signup,tolstoy auth loginortolstoy auth status. Use it as the SDK’sappKey, not the secret API key on theKey:line. - With the MCP,
list_workspacesreturns the app key ascurrentAppKey. - In Tolstoy, go to Settings → API, MCP & CLI → API, and copy App Key (https://platform.gotolstoy.com/settings/api-keys). The key is there on every plan, with no widget.
3. Send events
The E-commerce Analytics SDK is an ES module on the Tolstoy CDN. Create one SDK on the page, and calltrack() for each event:
tolstoy-sdk.<name>, for example tolstoy-sdk.add_to_cart. Parameters are strings, numbers and booleans. The Tolstoy SDK page has the limits of names and parameters.
4. Follow the shopper’s consent
The SDK sends no event until the shopper allows analytics, and it drops the events from before that. If the store has a consent banner, settolstoy-cookie-policy in localStorage to accepted or rejected from its answer, before the first event. With no consent tool on the page and no stored value, the SDK sends the events. Shopper consent has the code for Shopify.
5. Confirm delivery today
The report does not show today’s events, so check the requests. The SDK sends each event as onePOST request to https://analytics-v2.gotolstoy.com/event. It sends the queued events every 10 seconds, when 10 events are in the queue, and when the shopper leaves the page.
- HTTP 200: Tolstoy received the event. The body of the request holds
eventName(tolstoy-sdk.<name>) andappKey. Check that both are right. - No request: the shopper’s consent blocks analytics, or the next batch has not been sent yet. Wait 10 seconds, or leave the page.
6. Read your events
From about 06:30 UTC on the next day, ask for the report of the day that you sent the events:events lists each event name with its widget type, the number of events and the number of shoppers. Your events have the widget type tolstoy-sdk and the name tolstoy-sdk.<name>.
- The period is whole UTC days, up to 180 days. A period that reaches today stops at the end of yesterday.
--app-urlselects a store fromtolstoy stores list. Without it, the CLI uses the store that it saved at sign-in.scope.appUrlin the report names the store that the report read, andstoreslists all the stores of the workspace.
get_store_analytics with dateFrom, dateTo and sections: ["details"]. It returns the same report.
Tools for your agent
- Skills.
npx skills@latest add https://developers.gotolstoy.com --skill ecommerce-analyticsinstalls the ecommerce-analytics skill into the project. It tells an agent what to measure in a store, which events to send, how to work out rates from the counts of the report, and how to judge a number against benchmarks per vertical from Tolstoy’s store data.npx skills@latest add https://developers.gotolstoy.com --skill store-analyticsinstalls the store-analytics skill, which tells an agent how to read the report and what each number means. - Project note. Add a note to the
AGENTS.mdfile of the store’s project: the store sends its events with the Tolstoy SDK, andtolstoy analytics get-store-analyticsreads their counts. The next agent on the project then finds them. - Reference. Tolstoy SDK for the SDK, Tolstoy CLI for the CLI, and Connect your agent for the MCP.