---
title: "Read your traffic"
description: "Read how many customers visited, where they came from, how they bought and which apps called your store."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read your traffic

Your store counts what its customers do on every channel: the storefront, your own front end through the customer API, your customers' apps through the customer MCP server, and feeds. It sets no cookie and keeps no address or lasting id for a visitor who isn't signed in, so the store shows no cookie banner for it. [Customer analytics](/overview/analytics) says what it counts and keeps. Four operations read the counts back, each over a range of your store's days, beside the span right before it, like the other stats:

- <a href="/merchant-api/reference/traffic-stats/">`GET /traffic/stats`</a>: views and visitors, by kind of page, channel, country and product, with sign-ins (sign-ups included), sign-ups, and where visits came from (`sources`).
- <a href="/merchant-api/reference/conversion-stats/">`GET /conversion/stats`</a>: product views to checkouts started to orders, by channel and product.
- <a href="/merchant-api/reference/product-traffic-stats/">`GET /products/{product}/traffic/stats`</a>: one product's views, visitors and conversion, by channel.
- <a href="/merchant-api/reference/call-stats/">`GET /calls/stats`</a>: the calls your customers' apps made over the customer API and MCP, by channel and app.

How a product did in its launch week, beside the week before:

```bash
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/traffic/stats?from=2026-11-01&to=2026-11-07' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/traffic/stats', {
  query: [
    ['from', '2026-11-01'],
    ['to', '2026-11-07'],
  ],
});
```

Answers `200`, abridged:

```json
{
  "time_zone": "Europe/Rome",
  "from": "2026-11-01",
  "to": "2026-11-07",
  "previous_range": {
    "from": "2026-10-25",
    "to": "2026-10-31"
  },
  "rolled_through": "2026-11-14",
  "covered_from": "2026-10-20",
  "product_views": {
    "current": 1840,
    "previous": 95
  },
  "checkouts_started": {
    "current": 212,
    "previous": 4
  },
  "orders": {
    "current": 61,
    "previous": 1
  },
  "rates": {
    "current": {
      "view_to_checkout": 0.1152,
      "checkout_to_order": 0.2877,
      "view_to_order": 0.0332
    },
    "previous": {
      "view_to_checkout": 0.0421,
      "checkout_to_order": 0.25,
      "view_to_order": 0.0105
    }
  },
  "estimated": false,
  "visitors": {
    "current": 1210,
    "previous": 71
  }
}
```

The store-wide reads need `transaction:read`, as store stats do, and the product's needs `product:read`. An app's name in the call stats shows only to a token that may read your apps (`client:read`); otherwise it is `null`.

## Ranges and days

Each read takes `from` and `to`, store-local days spanning 366 days at most (the last 30 days by default), and how its `series` is cut: by `day` (the default), `week` or `month`. Every figure is a pair: `current` for the range and `previous` for the span before it.

The counts are added up once a day, after each of your store's days ends, so today counts nothing yet. Two fields say what the counts cover:

- `rolled_through` is the last day counted. Later days count nothing yet, and a conversion counts its orders only through that day too, so a sale today never sits over views not counted yet.
- `covered_from` is the first day counted (counts are kept for 13 months). Earlier days count nothing, and when the span before the range doesn't lie wholly between `covered_from` and `rolled_through`, every `previous` figure is `null`, so growth from nothing never reads as a jump. Product figures may start later, as their own `covered_from` in the product lists says.

## Visitors

A visitor is told apart only within one day, and never followed to the next, so `visitors` adds up each day's unique visitors: one person who comes back on three days counts three times. A week's visitors are each of its days' visitors added up.

## Where visits came from

A visit is a visitor's first page, on your storefront or your own front end alike. In the traffic stats, `sources` counts them three ways:

- `top_referrers`: the sites that linked to yours, by host, with a direct visit (no referring site) as `null`.
- `top_campaigns`: the `utm_source`, `utm_medium`, `utm_campaign` and `ref` of the page a visit landed on, each `null` when the link carried none, with `untagged` for visits whose link carried no tag at all.
- `by_device`: `mobile` for phones, `desktop` for computers and tablets alike, `null` when the device is unknown.

`top_referrers` and `top_campaigns` each list the 20 with the most visits beside their `total`, and `other` adds up the rest; `by_device` lists every device. Each day keeps only its 100 most visited hosts and campaigns, beside its direct and untagged visits, which are always kept, so a host or campaign is counted on the days it made that day's top, and a figure that may have missed some days is marked `estimated`. A direct visit counts in `top_referrers` like a host, while untagged visits stay apart from `top_campaigns`.

Visits have their own `covered_from` in `sources`, which may come after the answer's: the first day counted that held a visit, as visits from before your store recorded where they came from name nowhere. Until a visit is counted, it is `null`.

## Estimates

On a very busy store, counts are sampled: views and the other counts are scaled back up, and visitors are told apart within the sample, so they may read low. A figure counted from sampled data comes with `estimated: true`, on the answer, on each row of a breakdown and at each step of the series. The store's and a product's orders never are, as they are counted from your orders themselves; a channel's orders come from the counts, so they may be.

## Conversion

The steps count apart, so a rate can pass 1:

- **Product views** and **checkouts started** leave out visits from you and your staff, and from crawlers. A cart counts for the product of its first line.
- **Orders** are the ones placed through your store's checkout (never a renewal, nor an order recorded through the API or by hand), including a test purchase of your own.

Orders record no channel, so in `by_channel` a channel's orders are the purchases completed through it, which need not add up to the store's orders.

Source: https://docs.sherpo.io/merchant-api/guides/read-traffic/index.mdx
