> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/analytics.md).

# Analytics

For metrics, dimensions and worked examples, see \[Analytics: metrics and dimensions]\(https\://developers.spiffy.co/guides/analytics-metrics-and-dimensions).

Analytics queries and capabilities

## Query analytics: revenue, orders, AOV, LTV, conversion rate, MRR, subscriptions, refunds — as totals, time series, or attribution breakdowns

> Runs an analytics query for the merchant account.\
> \
> groupBy 'interval' returns a day/week/month time series.\
> groupBy a dimension breaks orders-family metrics down by attribution source.\
> \
> Metrics (13 total):\
> &#x20; Orders family (support dimension breakdowns): revenue, orders, aov, customers, conversion\_rate, ltv\
> &#x20; Subscriptions family (interval only): active\_subscriptions, new\_subscriptions, churned\_subscriptions, mrr\
> &#x20; Billing family (interval only): refunds, refund\_count, failed\_payments\
> \
> Dimensions (7): channel, utm\_source, utm\_medium, utm\_campaign, utm\_term, utm\_content, referring\_domain\
> \
> compare: pass 'previous\_period' for automatic period-over-period comparison,\
> or a custom { start, end } object for an explicit comparison window.\
> \
> Dates must be UTC ISO 8601 (e.g. '2026-04-13T00:00:00Z').\
> Call get\_analytics\_capabilities for the full metric/dimension/groupBy compatibility matrix.\
> \
> Example — revenue last month vs previous period:\
> &#x20; { "object":"account", "groupBy":"interval", "grouping":"day",\
> &#x20;   "metrics":\["revenue"], "period":{"start":"2026-06-01T00:00:00Z","end":"2026-06-30T23:59:59Z"},\
> &#x20;   "compare":"previous\_period" }

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"analytics","description":"Analytics queries and capabilities"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["analytics"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"AnalyticsQueryRequest":{"type":"object","properties":{"object":{"type":"string","enum":["account","checkout","product"],"description":"Query scope: 'account' for account-wide analytics, or 'checkout' to scope to a single checkout (requires objId). 'product' is not yet supported."},"objId":{"type":"string","description":"Id of the scoped object. Required when object is 'checkout'; omit for 'account'."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric keys to return (e.g. ['revenue', 'mrr', 'refunds']). Omit for the default orders-family set. See get_analytics_capabilities for all keys and their groupBy compatibility."},"groupBy":{"type":"string","description":"'interval' for a time series, or a dimension key (channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, referring_domain) for an attribution breakdown — see get_analytics_capabilities."},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"description":"Primary date range. start/end are UTC ISO 8601 strings (e.g. '2026-06-01T00:00:00Z'); timezone offsets are not interpreted."},"compare":{"anyOf":[{"type":"string","enum":["previous_period"]},{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},{"nullable":true}],"description":"Optional comparison window: 'previous_period' for the automatically-derived preceding window of equal length, or a custom {start, end} object (UTC ISO 8601). Adds a `previous` value to every metric cell."},"grouping":{"type":"string","enum":["day","week","month"],"description":"Bucket size when groupBy is 'interval'. Defaults to 'day'."},"touch":{"type":"string","enum":["first","last"],"description":"Attribution touch for dimension breakdowns: 'last' (default) groups by the last-touch snapshot, 'first' by the first-touch snapshot. Ignored for groupBy 'interval'; conversion_rate is visit-grain and unaffected."}},"required":["object","groupBy","period"]},"AnalyticsQueryResponse":{"type":"object","properties":{"groupBy":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"comparison":{"type":"object","nullable":true,"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"anyOf":[{"type":"string"},{"type":"number"}]},"label":{"type":"string"},"meta":{"type":"string"},"metrics":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"}},"required":["value"]}}},"required":["key","label","metrics"]}},"totals":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"}},"required":["value"]}}},"required":["groupBy","period","comparison","groups","totals"]},"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/analytics/query":{"post":{"tags":["analytics"],"summary":"Query analytics: revenue, orders, AOV, LTV, conversion rate, MRR, subscriptions, refunds — as totals, time series, or attribution breakdowns","description":"Runs an analytics query for the merchant account.\n\ngroupBy 'interval' returns a day/week/month time series.\ngroupBy a dimension breaks orders-family metrics down by attribution source.\n\nMetrics (13 total):\n  Orders family (support dimension breakdowns): revenue, orders, aov, customers, conversion_rate, ltv\n  Subscriptions family (interval only): active_subscriptions, new_subscriptions, churned_subscriptions, mrr\n  Billing family (interval only): refunds, refund_count, failed_payments\n\nDimensions (7): channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, referring_domain\n\ncompare: pass 'previous_period' for automatic period-over-period comparison,\nor a custom { start, end } object for an explicit comparison window.\n\nDates must be UTC ISO 8601 (e.g. '2026-04-13T00:00:00Z').\nCall get_analytics_capabilities for the full metric/dimension/groupBy compatibility matrix.\n\nExample — revenue last month vs previous period:\n  { \"object\":\"account\", \"groupBy\":\"interval\", \"grouping\":\"day\",\n    \"metrics\":[\"revenue\"], \"period\":{\"start\":\"2026-06-01T00:00:00Z\",\"end\":\"2026-06-30T23:59:59Z\"},\n    \"compare\":\"previous_period\" }","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsQueryRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsQueryResponse"}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## List available analytics metrics, dimensions, and groupings

> Returns the analytics catalog as data: every metric with its family, kind (flow/stock/derived), date anchor, and compatible groupBy values, plus dimensions, intervals, and comparison modes. Call this before query\_analytics to construct valid queries.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"analytics","description":"Analytics queries and capabilities"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["analytics"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"AnalyticsCapabilitiesResponse":{"type":"object","properties":{"objects":{"type":"array","items":{"type":"string"}},"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"format":{"type":"string"},"family":{"type":"string"},"kind":{"type":"string"},"description":{"type":"string"},"group_by":{"type":"array","items":{"type":"string"}},"anchor":{"type":"string"}},"required":["key","label","format","family","kind","description","group_by"]}},"dimensions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"]}},"intervals":{"type":"array","items":{"type":"string"}},"compare":{"type":"array","items":{"type":"string"}}},"required":["objects","metrics","dimensions","intervals","compare"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/analytics/capabilities":{"get":{"tags":["analytics"],"summary":"List available analytics metrics, dimensions, and groupings","description":"Returns the analytics catalog as data: every metric with its family, kind (flow/stock/derived), date anchor, and compatible groupBy values, plus dimensions, intervals, and comparison modes. Call this before query_analytics to construct valid queries.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsCapabilitiesResponse"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```
