Analytics
Two endpoints let you query your store's analytics programmatically and discover what's available:
POST /v2/analytics/query— run an analytics queryGET /v2/analytics/capabilities— discover available metrics, dimensions, and groupings
Both require the analytics OAuth scope and count against your monthly API quota.
Concepts
Metrics
Each metric belongs to a family that determines what data it reads:
orders
revenue, orders, customers, aov, ltv, conversion_rate
subscriptions
active_subscriptions, new_subscriptions, churned_subscriptions, mrr
billing
refunds, refund_count, failed_payments
A single query can mix metrics from different families.
Metrics are also classified by kind:
flow — counted over a bucket window (e.g. revenue collected, new subscriptions started)
stock — value at the end of the bucket (e.g. active subscriptions, MRR at period close)
derived — computed in the server after the main queries run (aov = revenue / orders; ltv = revenue / customers)
groupBy
groupBy controls how results are sliced:
groupBy: 'interval'withgrouping: 'day' | 'week' | 'month'— returns a time series, one bucket per interval.groupBy: <dimension>— breaks orders-family metrics down by an attribution dimension. Supported dimensions:channel,category,utm_source,utm_medium,utm_campaign,utm_term,utm_content,referring_domain. Subscription and billing metrics do not support dimension grouping; requests that mix them with a dimensiongroupBywill return a 400.
Call GET /v2/analytics/capabilities to see which group_by values each metric supports.
Revenue and the Sales stat
revenue is dated by when payment was collected (order_payments.created_at), not when the order was placed. This is the same date basis as the dashboard Sales stat, so the revenue total from an analytics query matches what you see on the dashboard for any given window. Refunds are not deducted from revenue; they appear separately as the refunds metric.
Periods and timezones
All dates are UTC ISO 8601. There is no per-account timezone applied to analytics queries. If you need to convert from a local timezone, use the convert_to_utc MCP tool or convert before sending.
POST /v2/analytics/query
Run an analytics query for your account or a specific checkout.
Request body
object
'account' or 'checkout'
Yes
Scope of the query. 'account' covers all orders; 'checkout' scopes to a specific checkout.
objId
number
When object is 'checkout'
The checkout ID to scope to.
groupBy
string
Yes
'interval' for a time series, or a dimension name for an attribution breakdown.
grouping
'day', 'week', 'month'
When groupBy is 'interval'
The bucket size.
metrics
string[]
No
Which metrics to return. Defaults to orders-family metrics.
period
{ start, end }
Yes
UTC ISO 8601 start and end of the query window.
compare
'previous_period' or { start, end }
No
When set, each metric cell includes a previous value from the comparison window.
Response shape
Values are in cents. Stock metrics (active_subscriptions, mrr) report the end-of-period value in totals, not a sum across buckets.
When compare is set, each metric cell includes a previous field:
Example: revenue and MRR by day, last 30 days
Response:
Example: revenue by channel with period comparison
Validation errors
An unknown metric or an incompatible metric/groupBy combination returns a 400 with a message that names the offending metric and lists valid alternatives. For example, requesting mrr with groupBy: 'channel' returns:
GET /v2/analytics/capabilities
Returns the full metric catalog so you can discover what's available without reading the docs.
Response:
group_by on each metric lists the groupBy values that metric supports. Use this to validate requests before sending them.
Last updated