Get sitewide snapshot

Retrieve sitewide snapshot metrics for a time window.

Parameters

• start — optional ISO 8601 datetime string. Beginning of the analysis window. Defaults to the start of the week (Monday, store timezone) containing the date one week ago — so the default window spans 7 to 13 days depending on the current weekday.
• end — optional ISO 8601 datetime string. End of the analysis window. Defaults to now (rounded to the cache interval). Period-over-period pct_change is computed against the equivalent window immediately preceding start.
• feature — optional metric-set selector object. See below.
• filters — optional shared sitewide filters object. See the Filters Reference.

The window is start / end, not startTs / endTs. Every /analytics/sitewide/* endpoint takes ISO 8601 datetime strings under start and end. The epoch-seconds startTs / endTs pair used by the experience endpoints (/analytics/resource/{experienceId}, /analytics/experience/{experienceId}/timeseries, /analytics/experience/{experienceId}/export) is not accepted here: unknown fields are stripped rather than rejected, so a request sending startTs / endTs returns 200 over this endpoint's default window — from the start of the week (Monday, store timezone) one week ago until now — instead of the range you asked for, and nothing in the response flags the substitution. The default differs per sitewide endpoint, so always pass an explicit start when you need a specific window. Date-only strings and datetimes without an offset are rejected — send a full datetime with Z or an offset ("2026-06-01T00:00:00Z", not "2026-06-01" or "2026-06-01T00:00:00").

The optional feature parameter is an object, not a string enum. It selects which metric set is returned.

These sets belong to this endpoint. They are not the same as the sets on POST /analytics/sitewide/timeseries — the two endpoints compute different metrics, so a set with the same name returns different fields on each.

Omitting feature entirely returns the full sitewide metric set in a single "All" segment.

median_order_value and average_discount are available only on this endpoint. Conversely, the timeseries endpoint returns per-session rates (sessions_per_visitor, conversion_rate_per_session, net_revenue_per_session, gross_profit_per_session) and cost_of_revenue, none of which are computed here.

Response Structure

The response is a JSON object keyed by segment name, not a flat object with top-level metric fields.

When no audience feature is specified (or feature.name is "performance", "order", or "conversion"), the response contains a single "All" key:

{
  "All": {
    "currency": "USD",
    "n_visitors": { "value": 52763, "pct_change": 0.12 },
    "conversion_rate": { "value": 0.034, "pct_change": -0.05 },
    ...
  }
}

When feature.name is "audience", the response contains one key per audience segment plus a "__total" key:

{
  "Desktop": { "currency": "USD", "n_visitors": { "value": 30000, "pct_change": 0.08 }, ... },
  "Mobile": { "currency": "USD", "n_visitors": { "value": 22763, "pct_change": 0.18 }, ... },
  "__total": { "currency": "USD", "n_visitors": { "value": 52763, "pct_change": 0.12 }, ... }
}

A window with no data returns an empty object {} — not { "All": {} } and not a segment map with zeroed metrics. This applies to every feature, including audience (no "__total" key either). Check that the segment you want is present before reading metrics off it; response.All.n_visitors.value will throw on an empty window.

Each segment object contains currency (string), the COGS metadata fields cogs_configured (boolean) and cogs_coverage_pct (number), and metric fields. The two cogs_* fields are present for the performance, order, and audience features but omitted for conversion. Non-suppressed metric fields are objects whose value and pct_change cells are optional and nullable (number | null). pct_change represents the percent change versus the comparison period. In audience view, per-segment metrics can also include pct_impact_to_total_change (number | null).

An unavailable calculation is returned as null, including percent change when both current and comparison values are zero or when comparison data is missing. For example, pct_revenue_with_cogs can return { "value": 0, "pct_change": null } in a populated performance response. Null-check individual cells before using them; a present metric object does not guarantee numeric cells. This is separate from the whole-metric profit suppression described below.

impact_from_visitor_mix_shift appears on __total for ratio metrics only — within the audience field set that means conversion_rate, aov, net_revenue_per_visitor, and pct_revenue_with_cogs. (gross_margin_pct is a ratio but is not part of the audience field set, so it never carries this field.) Additive metrics (n_visitors, n_orders, net_revenue, gross_profit, and the rest of the counts and totals) never carry it, so expect it on a minority of the fields in a __total object rather than on all of them. It is the residual of the total percent change that is not attributable to any individual segment — the part explained by the mix of visitors shifting between segments — which is only meaningful for a weighted average, not for a sum.

Alongside currency, every segment also includes two scalar COGS-status fields (not { value, pct_change } objects): cogs_configured (boolean — whether cost-of-goods data is configured for the store) and cogs_coverage_pct (number, a fraction in [0, 1] for the share of revenue with COGS data).

COGS-dependent profit metrics are returned as a bare null (not a { value, pct_change } object) when cogs_configured is false. On this endpoint that is four fields:

• gross_profit
• gross_profit_per_visitor
• gross_margin_pct
• oli_net_product_revenue_with_cogs

Clients must null-check all four before reading .value / .pct_change. Within this endpoint the suppression is applied to any profit metric, so the same rule holds for other profit fields (for example gross_profit_per_order, product_profit, subscription_gross_profit) on the feature sets that return them.

Suppression is per endpoint, not global. It is applied on this endpoint, on POST /analytics/sitewide/timeseries, and on the experience analytics endpoints (POST /analytics/resource/{experienceId} and POST /analytics/experience/{experienceId}/timeseries, which report the same condition as cogsConfigured / cogsCoveragePct). It is not applied to orderBreakdown on POST /analytics/sitewide/order-distribution — see that endpoint's note before using its profit fields.

Metric Availability by Feature

• performance returns this KPI subset: n_visitors, conversion_rate, n_orders, aov, net_revenue, gross_profit, gross_profit_per_visitor, net_revenue_per_visitor, gross_margin_pct, average_discount, pct_revenue_with_cogs.
• order returns this subset: aov, n_visitors, n_orders, median_order_value, average_units_per_order, pct_orders_with_free_shipping, net_shipping_revenue_per_order.
• conversion returns this subset: viewed_collection_page_rate, viewed_product_page_rate, add_to_cart_rate, checkout_begin_rate, conversion_rate, bounce_rate, abandoned_cart_rate, abandoned_checkout_rate.
• audience returns per-segment metrics plus a __total key: n_sessions, n_visitors, n_orders, gross_revenue, net_revenue, order_cogs, conversion_rate, aov, net_revenue_per_visitor, shipping_cost, transaction_fees, tax, gross_profit, gross_profit_per_visitor, oli_net_product_revenue_with_cogs, oli_net_product_revenue, pct_revenue_with_cogs.

Rate Limit: 10 requests per 30s window, refilling 5 tokens every 30s.