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 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:
GET /traffic/stats: 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).GET /conversion/stats: product views to checkouts started to orders, by channel and product.GET /products/{product}/traffic/stats: one product’s views, visitors and conversion, by channel.GET /calls/stats: 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:
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"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:
{
"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_throughis 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_fromis 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 betweencovered_fromandrolled_through, everypreviousfigure isnull, so growth from nothing never reads as a jump. Product figures may start later, as their owncovered_fromin 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) asnull.top_campaigns: theutm_source,utm_medium,utm_campaignandrefof the page a visit landed on, eachnullwhen the link carried none, withuntaggedfor visits whose link carried no tag at all.by_device:mobilefor phones,desktopfor computers and tablets alike,nullwhen 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.