Create a rule-defined audience
Creates a rule-defined audience. It lands ACTIVE and UNMATERIALISED: member_count is 0 and last_refreshed_at is null until the background sweeper runs or you call the refresh route, so do not read the create’s counts as the size of the audience. DYNAMIC ONLY. kind is refused by name, because a static segment’s membership is a list of marketing contact ids and no route on this API can supply one; a static segment created here would be a permanently empty audience with no error ever returned. Names are unique per store, so a repeat is 409 name_taken.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
What the merchant sees in their own dashboard. Unique per store, so a repeat is 409 name_taken rather than a second audience nobody can tell apart.
The selection tree, and what a dynamic segment IS. A node carries a type of group, field or behavior. A GROUP node carries op (and, or, not) and children. A FIELD node carries field, operator and value, where field is one of orders_count, total_spent_minor, created_at, last_order_at, last_open_at, last_click_at, last_activity_at, email_consent, sms_consent or push_consent. A BEHAVIOR node carries predicate (performed, not_performed), event, within_days and min_count. THE VOCABULARY IS CLOSED AND THE SERVER OWNS IT. An unrecognised field, operator, consent state or event name is a 400 naming what would have been accepted, not a rule that silently matches nobody. value's type is decided by the field it sits under: a number for a numeric field, a consent state string for a consent field, a list for the in operator, a day count for a relative time window. The tree may nest 8 levels and hold 200 nodes; past either it is 400 rule_too_complex.
Response
Created
