Statistics
The Statistics API exposes detailed store metrics — revenue, sales, transactions, conversion, average order value, and more — as JSON.
Overview
The Statistics API provides a single endpoint:
Each call returns one statistic as a time-bucketed series for the
selected period, the matching previous-period series for comparison, and a
server-computed change block summarising the delta. To pull several
statistics at once, call the endpoint in parallel with different type
values.
Stat types
| Type | Domain | Notes |
|---|---|---|
revenue | money | Gross order revenue |
sales | count | Completed orders |
transactions | count | Captured payment transactions |
checkout_sessions | count | Initiated checkouts |
customers | count | New paying customers |
conversion | rate | Checkouts that converted to a sale (%) |
recovered_revenue | money | Revenue rescued via abandoned-checkout follow-ups |
partners_revenue | money | Revenue attributed to your affiliate partners |
automation_runs | count | Automation triggers fired |
free_products | count | Free-product redemptions |
average_order_value | money | Average order value across completed orders |
average_customer_lifetime_value | money | Average lifetime spend per customer |
Money values are returned as integers in minor units (e.g. 12500 =
125.00 PLN). display_value strings carry a pre-formatted English-locale
version (e.g. "125.00 PLN", "28%", "42") so consumers can render the
headline without re-implementing currency formatting.
Currency is required
Every call requires a currency query parameter — figures are scoped to a
single currency. There is no store-level default; see
GET /store for the currencies your store
transacts in. Count-only stats (sales, transactions, etc.) still take
currency for API consistency and to keep their totals consistent with the
per-currency view elsewhere.
Date ranges and bucket sizes
The optional date parameter accepts either a named slug or a custom range
as YYYY-MM-DD,YYYY-MM-DD. Bucket size is derived from the range length:
| Range length | Bucket size |
|---|---|
| ≤ 14 days | Daily |
| ≤ ~100 days | Weekly |
| ≤ ~2 years | Monthly |
| longer | Yearly |
The previous-period series is auto-derived to be directly comparable: same length immediately before the selected range for daily and weekly buckets, and exactly one year back for monthly and yearly buckets.
Named slugs accepted: today, monthToDate, yearToDate, last7days,
last30days, last3months, last12months, all. The default is
last7days.
The change block
Every response carries a server-computed comparison between the selected and previous totals:
| Field | Meaning |
|---|---|
absolute | Signed delta selected_total.value - previous_total.value (may be negative) |
percentage | Rounded percentage change. 0 when the previous total was zero. |
direction | up (absolute > 0), down (absolute < 0), or flat |
direction and percentage are server-computed, so consumers can render
the delta indicator (e.g. ▲ +28%) without deriving it themselves.
Locale is always English
display_value strings are formatted under English locale regardless of
your store's locale settings. You always get "125.00 PLN", never
"125,00 zł". There is no lang or Accept-Language parameter.
Caching
Each unique combination of statistic type and filters is cached server-side for 120 seconds. Rapid repeat calls within that window return the same result — don't retry on identical parameters expecting a refresh.
Zero-activity responses
A date range with no activity returns a clean zero-shaped response
(data: [], totals at 0, change.direction: "flat") with a date_range
echoing the requested period — not an error.