For the complete documentation index, see llms.txt. This page is also available as Markdown.

Analytics

Two endpoints let you query your store's analytics programmatically and discover what's available:

  • POST /v2/analytics/query — run an analytics query

  • GET /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:

Family
Metrics

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' with grouping: '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 dimension groupBy will 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

Field
Type
Required
Description

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