Customers API
Customer APIs manage workspace-scoped customer identity and analysis. These endpoints are feature-gated behind revenue tracking.Feature gate
All/customers/* routes require revenue-tracking entitlement on the workspace plan.
Endpoint matrix
| Method | Path | Purpose |
|---|---|---|
GET | /customers | List customers with pagination/search |
GET | /customers/count | Count customers in workspace |
GET | /customers/:id | Fetch one customer (ext_ prefix supported for external ID lookup) |
POST | /customers | Create or upsert by externalId |
PATCH | /customers/:id | Update customer fields |
DELETE | /customers/:id | Soft-delete + PII scrub |
GET | /customers/cohorts | Cohort breakdown by time/campaign/source |
GET | /customers/ltv-cohorts | LTV cohorts over N months |
POST | /customers/:id/recalculate-ltv | Force LTV recompute |
GET | /customers/:id/journey | Event timeline for customer |
GET | /customers/:id/attribution | Click/link/campaign attribution record |
List query parameters (GET /customers)
| Param | Type | Notes |
|---|---|---|
page | number | Default 1 |
limit | number | Default 20, max 100 |
sortOrder | asc | desc | Defaults to desc |
search | string | Matches customer identity fields |
Cohorts query parameters (GET /customers/cohorts)
| Param | Type | Notes |
|---|---|---|
group_by | week | month | campaign | source | Invalid values return 400 |
start | date | Optional period start |
end | date | Optional period end |
Identity model
Customer stitching is strongest when you consistently provide:externalId(required stable identity)email(recommended)clickId(recommended for attribution continuity)
Delete behavior
Delete is soft-delete oriented for analytics integrity:- keeps conversion/event history
- scrubs customer PII fields
- marks record state as deleted for normal UI/API listing
Authorization and permissions
GETendpoints:links:readoranalytics:readdepending on route.- Mutations:
links:create,links:update,links:delete.
Caching behavior
Heavy read routes (cohorts, ltv-cohorts, journey, attribution) use short-lived snapshot caching for repeat queries.
Typical failures
404 NOT_FOUND: missing customer409 DUPLICATE_EXTERNAL_ID: external ID conflict on update503 SERVICE_UNAVAILABLE: analytics backend unavailable500 ANALYTICS_ERROR: analytics query execution failure
/api-reference/customers/cohorts-ltv-journey-and-attribution/user-guides/manual/data/events-and-customers-operations-reference/user-guides/manual/data/exports-and-operational-checks