CDP REST APIAPI Reference
Batch Update Profiles
Apply the same property writes to every in-scope profile matching a condition.
POST /cdp/profiles/batch applies the same property writes to EVERY in-scope profile
matching a Unomi condition. The condition is allowlist-validated at the edge, and your
brand's scope predicate is AND-injected server-side — a batch can only ever touch your own
profiles. The match set is capped to bound the blast radius, and the route is rate-limited
(both an edge throttle and a per-brand token bucket) because it is the heaviest write.
Every write is bound to your brand's shop scope. See Tenant Isolation & Scope.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
condition | string | Yes | — | Body field — the Unomi match condition. Allowlist-validated; the brand scope predicate is AND-injected server-side (a caller-supplied scope/shopDomain predicate is rejected). |
add | string | No | — | Body field — a { key: value } map of properties to set only if currently missing. |
update | string | No | — | Body field — a { key: value } map of properties to overwrite. |
delete | string[] | No | — | Body field — an array of property names to remove. |
Response
The 200 response body:
| Field | Type | Description |
|---|---|---|
matched | number | |
updated | number | |
status | 'accepted' | |
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 | The body is not valid JSON, or the condition object is missing. |
400 | invalid_condition | The condition failed the allowlist validator. |
400 | invalid_property | A reserved or malformed property key was written. |
400 | batch_too_large | The match set exceeds the batch cap — narrow the condition. |
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 POST. |
429 | rate_limited | Too many batch requests for this brand — retry shortly. |
500 | internal_error | An unexpected error prevented the batch write. |