> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gotolstoy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-commerce Analytics SDK

> Free e-commerce analytics for a store that you or your AI agent builds: track storefront events such as product views and add to carts with the E-commerce Analytics SDK, and read how many times each event happened and how many shoppers sent it with the Tolstoy CLI or MCP.

This page takes an AI agent from no Tolstoy account to reading the analytics events of the store that it builds, using the E-commerce Analytics SDK (the `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](https://developers.gotolstoy.com/agents/ecommerce-analytics.md). All pages: [https://developers.gotolstoy.com/llms.txt](https://developers.gotolstoy.com/llms.txt).

If you are a person, give your agent this prompt:

```text theme={null}
Add e-commerce analytics to this store with Tolstoy. Follow https://developers.gotolstoy.com/agents/ecommerce-analytics.md
```

## What you get

Your storefront code sends events with the E-commerce Analytics SDK, for example `product_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.

Sending events and reading the report are free on every Tolstoy plan, the free plan included. Your events never count toward Shoppable Videos view billing.

You do not need a Tolstoy widget on the store. Tolstoy also makes shoppable video, try-on and chat widgets, and AI images and videos for e-commerce brands; the SDK and the report work without them.

## 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:

1. 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.
2. The approval of the sign-in of the Tolstoy CLI or the Tolstoy MCP, on the page that the sign-in opens.

If you cannot use a browser or read the inbox, ask the person that you work for to do these steps.

## 1. Create the account and sign in

With the [Tolstoy CLI](https://developers.gotolstoy.com/agents/cli.md):

```bash theme={null}
npm install -g @tolstoy-ai/cli
tolstoy auth signup
```

`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](https://developers.gotolstoy.com/agents/connect.md), sign up at [https://platform.gotolstoy.com/signup](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](https://developers.gotolstoy.com/agents/connect.md) 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 by `tolstoy auth signup`, `tolstoy auth login` or `tolstoy auth status`. Use it as the SDK's `appKey`, not the secret API key on the `Key:` line.
* With the MCP, `list_workspaces` returns the app key as `currentAppKey`.
* In Tolstoy, go to **Settings** → **API, MCP & CLI** → **API**, and copy **App Key** ([https://platform.gotolstoy.com/settings/api-keys](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 call `track()` for each event:

```html theme={null}
<script type="module">
  import { TolstoySDK } from 'https://widgets-sdk.gotolstoy.com/tolstoy-sdk.js';

  const tolstoy = new TolstoySDK({ appKey: 'YOUR_APP_KEY' });

  tolstoy.analytics.track('product_view', { productId: 'classic-tee' });

  document.querySelector('#add-to-cart').addEventListener('click', () => {
    tolstoy.analytics.track('add_to_cart', { productId: 'classic-tee', quantity: 1 });
  });
</script>
```

Tolstoy records each event as `tolstoy-sdk.<name>`, for example `tolstoy-sdk.add_to_cart`. Parameters are strings, numbers and booleans. The [Tolstoy SDK](https://developers.gotolstoy.com/storefront/tolstoy-sdk.md) 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, set `tolstoy-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](https://developers.gotolstoy.com/storefront/tolstoy-sdk.md#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 one `POST` 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>`) and `appKey`. 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.

To see the requests, open the network log of the browser, or record the requests with a browser automation tool such as Playwright. On the day that you send, HTTP 200 is the only check. The report shows the counts the next day.

## 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:

```bash theme={null}
tolstoy analytics get-store-analytics \
  --date-from 2026-11-16 \
  --date-to 2026-11-16 \
  --sections '["details"]' \
  --json
```

In the JSON, `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-url` selects a store from `tolstoy stores list`. Without it, the CLI uses the store that it saved at sign-in. `scope.appUrl` in the report names the store that the report read, and `stores` lists all the stores of the workspace.

With the MCP, call `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-analytics` installs 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-analytics` installs 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.md` file of the store's project: the store sends its events with the Tolstoy SDK, and `tolstoy analytics get-store-analytics` reads their counts. The next agent on the project then finds them.
* **Reference.** [Tolstoy SDK](https://developers.gotolstoy.com/storefront/tolstoy-sdk.md) for the SDK, [Tolstoy CLI](https://developers.gotolstoy.com/agents/cli.md) for the CLI, and [Connect your agent](https://developers.gotolstoy.com/agents/connect.md) for the MCP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.