Get a site's add-to-cart insights
Returns what the add-to-cart counts do not give. First, the sessions that added to the cart: of the sessions that had a conversation, and of the sessions where the assistant was shown and no conversation started, how many there were and how many added to the cart (counts only; divide to get a rate). A session with a conversation counts as having added when it made an add in the panel, or an add on the merchant's pages that the server received after its first conversation started. Second, the median cart value per currency, for the carts with a conversation and for the others: a cart is the set of add-to-carts that carry the same cart token, valued by the sum of its lines' amounts in the currency, and with a conversation when one of its lines is. Medians are in the currency's minor unit, never summed across currencies. Third, the add-to-carts by device (highest first), by hour of the day in the time zone asked (24 counts, zero-filled) and by unit price per currency (the amount divided by the quantity added, in five bands: under 25, 25 to 49, 50 to 99, 100 to 199 and 200 and over, in major units of the currency). Fourth, the dates from which amounts and cart tokens are recorded. The groups are of sessions and carts that had a conversation, not of what the assistant added: shoppers who start a conversation are not a random sample. A figure is `null`, never zero, while it could not have been recorded. No event, session or cart id is returned. Shopify stores only. Read-only.
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Path Parameters
The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.
Query Parameters
First UTC day of the period, included (YYYY-MM-DD).
^\d{4}-\d{2}-\d{2}$Last UTC day of the period, included (YYYY-MM-DD). On or after from.
^\d{4}-\d{2}-\d{2}$Keep the cart values of this currency alone (three letters, any case, such as USD). Left out, every currency has its own row. The session counts are unchanged.
^[A-Za-z]{3}$Count only the events that recorded this device (desktop, mobile, tablet or unknown). One value. Left out, every device. The two recorded-from dates do not follow it.
Value in
- "desktop"
- "mobile"
- "tablet"
- "unknown"
The IANA time zone the hours of the day are counted in, such as Europe/Paris. Left out, UTC. The period itself stays whole UTC days.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/sites/string/add-to-cart-insights?from=string&to=string"{ "data": { "from": "2026-10-01", "to": "2026-10-07", "rate": { "withConversation": { "sessions": 2264, "added": 336 }, "withoutConversation": { "sessions": 47307, "added": 3894 } }, "cartValue": [ { "currency": "USD", "withConversation": { "carts": 99, "medianMinor": 9000 }, "withoutConversation": { "carts": 687, "medianMinor": 8678 } } ], "amountsSince": "2026-10-23T09:12:44.000Z", "cartTokensSince": "2026-10-23T09:12:44.000Z", "devices": [ { "device": "mobile", "count": 14930 }, { "device": "desktop", "count": 3278 } ], "hours": [ 12, 8, 5, 3, 2, 2, 4, 9, 18, 30, 42, 55, 60, 58, 52, 49, 47, 50, 61, 70, 66, 52, 35, 20 ], "timeZone": "Europe/Paris", "priceBands": [ { "currency": "USD", "bands": [ { "min": 0, "max": 25, "count": 1316 }, { "min": 25, "max": 50, "count": 531 }, { "min": 50, "max": 100, "count": 906 }, { "min": 100, "max": 200, "count": 256 }, { "min": 200, "max": null, "count": 114 } ] } ] }}Get a site's revenue and the assistant's share
Returns the net revenue and orders of the whole site over a period, the revenue and orders attributed to the assistant, the average order value of each, the assistant's conversion rate, and the same figures over time. The period is two UTC calendar days, both included, up to 366 days. Amounts are integers in the minor units of `currency` (cents for EUR), net of refunds and cancellations, after discounts and before shipping, and are never added across currencies: the response holds one currency, and `currencies` lists the ones the period has orders in. The assistant's revenue is attributed, never incremental: an order counts when a conversation touched it within `windowHours` before the order (last touch). An assistant figure is `null` when it is not measured (the site has minted no join key yet), never zero. Pass `compare=true` to get the previous period of the same length in `previous`. The series is per UTC hour on a period of two days or fewer and per UTC day beyond, every bucket present. Read-only.
Get a site's holdout test
Returns the site's holdout test, as the Holdout tab of the site's settings shows it: the running test, otherwise the most recent ended one. A holdout serves half of the sessions no assistant (a fixed 50/50 split, chosen by browser session) and compares the share of sessions with an add-to-cart between the two groups, counting an add-to-cart from the assistant's panel or from the merchant's page. No verdict is returned before both groups reach the traffic floor, and an inconclusive result gives the smallest gap the test could confirm (`detectionLimitPoints`), never a claim of no difference. While a test runs, reading it checks that its split is still even and ends it as invalid when it is not. `404` when the site has never had a holdout.