Date ranges
Four endpoints take start and end: /data/analytics/summary, /data/analytics/stats, /data/analytics/top, and /data/analytics/coverage.
Format
?start=2026-08-01&end=2026-08-26YYYY-MM-DD, and both bounds are inclusive. To cover all of 14 April, end on 2026-04-14.
The 90-day cap
summary, stats and top refuse a range wider than 90 days:
{ "success": false, "data": null, "error": "Date range cannot exceed 90 days" }Status 422. The call is refused rather than trimmed, so you always know exactly what a number covers. For a longer view, walk it in 90-day windows — or use /data/analytics/lifetime, which is all-time and takes no range at all.
Defaults
Omit both bounds and you get the last 30 days — today included, matching the app's own "Last 30 days".
Supply only one and the other is anchored to it, never to now:
| You send | You get |
|---|---|
| Neither | The last 30 days |
start only | From that date to today |
end only | The 30 days ending on that date |
Always read appliedWindow
Every range endpoint returns the window it actually ran:
{
"appliedWindow": { "start": "2026-07-28", "end": "2026-08-26", "source": "default_30d" }
}source | Meaning |
|---|---|
merchant | You supplied both bounds |
partial_default | You supplied one; the other was anchored to it |
default_30d | You supplied neither |
start=last%20week falls back to the default window and returns 200. The only way to tell is appliedWindow.source. Check it before labelling a chart, or you will publish "last week" over a figure covering thirty days.Days belong to your store
Ranges are aligned to your store's timezone, the same way the Analytics dashboard aligns them. "Today" means your store's today, not UTC's, so a figure here and the same figure on the dashboard agree.
Comparing periods
There is no built-in comparison. Make two calls and compare them yourself:
const july = await read('/data/analytics/summary', {start: '2026-07-01', end: '2026-07-31'});
const august = await read('/data/analytics/summary', {start: '2026-08-01', end: '2026-08-31'});
const lift = august.totalUpsoldValue - july.totalUpsoldValue;/data/analytics/lifetime. Lifetime figures are all-time totals, so subtracting one from the other produces a number that measures nothing.