CDP REST APIAPI Reference
Brand Overview
A one-call snapshot of your brand's customer base — totals, tag distribution, spend, and recent event volume.
GET /cdp/overview summarizes your brand's entire customer base in one call — the
"how are my customers doing?" snapshot, instead of ten separate lookups. It is the
REST twin of the cdp_overview MCP tool: both return the same data, computed by one
shared capability, so the two surfaces cannot drift.
Every read is bound to your brand's shop scope. See Tenant Isolation & Scope.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
since_days | number | No | 30 | Length of the recent-event window in days. Clamped to [1, 365] — an out-of-range value is clamped, a non-numeric value returns 400. |
Response
The 200 response body:
| Field | Type | Description |
|---|---|---|
totals | object | Base counts across your customer base. |
totals.customers | number | Count of your materialized customer profiles. |
totals.identifiedProfiles | number | null | Identified (known-contact) profiles from the CDP profile store; null when that store is degraded. |
totals.anonymousProfiles | number | null | Anonymous (pixel-only) profiles, derived as total minus identified; null when the profile store is degraded. |
totals.orders | number | null | CDP-witnessed order count (since ingest, not lifetime store history); null when the commerce reads degraded. |
totals.products | number | null | Distinct product keys seen in the product rollup; 0 before backfill, null when the commerce reads degraded. |
tagDistribution | object[] | Per-derived-tag customer counts, busiest tag first. |
tagDistribution[].tag | string | The derived tag (e.g. high_value, lapsed). |
tagDistribution[].count | number | How many of your customers carry this tag. |
spend | object | Spend aggregates over your materialized profiles. |
spend.avgTotalSpend | number | null | Mean lifetime spend within the modal-currency cohort; null for an empty base. |
spend.avgAov | number | null | Mean average-order-value within the modal-currency cohort; null for an empty base. |
spend.currency | string | null | Modal (most common) currency the averages are denominated in. |
spend.mixedCurrency | boolean | true when your base transacted in more than one currency. |
recentEvents | object | Recent event volume and the window it covers. |
recentEvents.since | string | ISO-8601 lower bound of the window (inclusive). |
recentEvents.sinceDays | number | The effective (clamped) window length in days. |
recentEvents.byEventType | object[] | Per-event-type counts over the window, busiest first. |
recentEvents.byEventType[].eventType | string | The event type. |
recentEvents.byEventType[].count | number | Event volume within the window. |
degraded | object | Which optional sources degraded on this call. |
degraded.unomi | boolean | true when the profile store was briefly unavailable — the identified/anonymous counts come back null while every Postgres-derived field still returns. |
degraded.commerce | boolean | true when the commerce reads were unavailable — totals.orders/totals.products come back null while everything else still returns. |
scope | string | Your brand's resolved shop domain. |
Errors
All errors share the standard envelope { "error": string, "error_description": string }.
| Status | Code | When |
|---|---|---|
400 | bad_request | since_days is present but not a number. |
401 | unauthorized | Missing or invalid API credential. |
403 | forbidden | No connected Shopify integration resolves a scope for the brand. |
405 | method_not_allowed | The request used a method other than GET. |
503 | upstream_unavailable | The CDP is temporarily unavailable — retry. |
500 | internal_error | An unexpected error prevented computing the overview. |