Customer Groups

Customer Groups require customer scopes: reads use read_customers and writes use write_customers. Manual groups have members you add or remove. Automatic groups select members from their saved rules. A group's type cannot change after creation.

For lifetime_spend and orders_count, use gte or lte with a non-negative decimal string in value and omit value_id. Read GET /customer-groups/limits before constructing inputs: each numeric operator includes decimal_places and max_value. Spending operators also include currency with the store base currency code, symbol, and display precision. Use decimal_places for accepted amount precision; currency display precision can differ.

Create, rule updates, and preview use the same validation. Invalid spending precision or bounds return HTTP 400 GROUP_RULE_MONEY_INVALID; invalid order counts return GROUP_RULE_ORDER_COUNT_INVALID. Malformed numeric values can return GROUP_RULE_NUMBER_INVALID, and unrelated references return GROUP_RULE_VALUE_SHAPE_INVALID. Saved rule values remain decimal strings; General display preferences do not change their meaning. Existing saved thresholds are not rounded automatically. Correct an invalid older threshold before resubmitting its rules.

Automatic Customer Groups can use last_purchase_at and purchased_product rules. Before authoring or previewing one, call GET /customer-groups/purchase-rule-readiness. This read endpoint requires read_customers; the credential determines the store.

While purchase history is being prepared, the endpoint returns available: false, status: refreshing, and reason: CUSTOMER_PURCHASE_FACTS_REFRESHING. Requests that create, change, preview, or evaluate purchase rules then return HTTP 409 with the same error code. Metadata-only updates, such as changing a group name without submitting rules, remain available. Retry after readiness becomes ready; do not interpret refreshing as no matching customers.

Purchase conditions count paid and cash-on-delivery orders with item quantity remaining after refunds. Cancelled, test, unpaid non-COD, and fully refunded orders do not count. A full monetary refund excludes the order even when no individual item quantities were marked as refunded. A fully refunded line no longer matches purchased_product; a partially refunded line still matches while eligible quantity remains. last_purchase_at is the latest order creation time among qualifying purchases, so an order can continue to set the date when another eligible item remains after refunds. Once readiness is complete, an eligible customer with no retained purchase matches last_purchase_at is_null and purchased_product excludes.

An invalid, deleted, or other-store parent product returns HTTP 400 with GROUP_RULE_PRODUCT_INVALID. Invalid dates or day ranges return GROUP_RULE_DATE_INVALID or GROUP_RULE_DURATION_INVALID; missing required values return GROUP_RULE_VALUE_REQUIRED. Extra values on an empty check or a value_id on a purchase-date rule return GROUP_RULE_VALUE_SHAPE_INVALID. Purchase-rule readiness only states whether these rules can be evaluated; it does not grant marketing consent.

Use the membership snapshot and change feed together when your integration needs a durable local copy of a Customer Group's membership. Both endpoints require read_customers. The credential determines the store, and each item contains only a customer UUID. The feed does not include customer profiles, contact details, or marketing-consent state; treat customer UUIDs as customer data and protect them accordingly.

Always take this initial snapshot, even if you plan to request changes from after_revision=0: revision 0 can already have members but has no change item for each preexisting membership. Keep the returned revision. If has_more is true, request the next page with cursor as the only query parameter. The cursor pins every snapshot page to the same revision and page limit. If membership changes while you paginate, the API returns CUSTOMER_GROUP_MEMBERSHIP_RESTART_REQUIRED; discard the partial snapshot and restart without a cursor. An automatic group that is still refreshing returns CUSTOMER_GROUP_MEMBERSHIP_REFRESHING and no customer IDs or cursor.

Apply changes in the returned order: revision ascending, then operation in the fixed order added, removed, group_deleted, then customer UUID. A page contains at most limit change items, including a group_deleted marker. revisions supplies counts and timestamps for exactly the revisions touched by that page; counts can cover items split across more than one page. Persist each operation idempotently. For a page with has_more, checkpoint next_cursor only after the complete page is durable. For the final page, checkpoint through_revision only after the complete traversal is durable. Pagination is pinned to through_revision, so changes committed later do not enter the traversal. Begin the next traversal with after_revision equal to that checkpointed through_revision.

A removed operation means that the customer left this group. It does not mean that the customer withdrew marketing consent, and an added operation does not grant consent. Read and process marketing consent through the customer contract separately.

Promotional campaign control groups are configured by staff in Store Admin or the mobile app and are not Store API resources. An integration can synchronize a Customer Group with these endpoints and run its own authorized experiment, but it must enforce destination consent, suppression, assignment and deletion rules itself. The membership feed cannot launch a Tringify campaign or place a customer into a Tringify campaign's message or control arm.

Cursors are opaque, bound to the credential's store, group, endpoint, page limit, and captured revision, and expire no later than 24 hours after the first page was issued. Continuation requests accept only cursor; changing limit or after_revision requires a new first page. Store cursors exactly as returned and never inspect or modify them.

Change history is retained for at least 30 days. history_floor_revision is the highest revision already removed; complete replay is available only when after_revision is at or above that floor. CUSTOMER_GROUP_MEMBERSHIP_CURSOR_EXPIRED means the cursor's 24-hour lifetime ended or required change history was removed; take a new snapshot instead of treating the result as no changes. The change feed remains readable after group deletion and ends with a group_deleted operation without a customer_id. After that marker is durable, discard the obsolete local membership mirror. Snapshot requests for a deleted group return CUSTOMER_GROUP_MEMBERSHIP_DELETED.

A merchant can connect a saved Customer Group to a webhook endpoint. The endpoint receives customer_group_membership.snapshot while a complete membership is synchronized, then customer_group_membership.changes for later revisions. These deliveries use the standard webhook JSON envelope and request signature described in Webhook events. Verify the signature against the raw request body, deduplicate by envelope event_id, and return a successful response only after durably accepting the batch.

Process batches by subscription_id, generation_number, and batch_sequence. generation is the opaque UUID for one synchronization epoch. generation_number increases when a fresh synchronization starts, and batch_sequence increases within that generation. HTTP requests can complete out of order. Stage a later sequence until earlier sequences in that generation are durable. When a larger generation number appears, discard partial work from older generations and build the replacement membership from the new snapshot.

Collect every snapshot batch for one generation and promote it as the current membership only after all sequences through the batch marked final: true are durable. An empty final snapshot is a valid empty group. final closes that snapshot or change-page sequence; it does not close the connection.

Apply changes in their supplied order and make each revision idempotent. added inserts a customer UUID and removed removes it. revisions describes the source revisions represented by the batch and can include a revision with no item changes. Use through_revision as the durable source checkpoint only after the complete batch is accepted. A checkpoint shown by Tringify means the batch was queued; it does not prove that your endpoint received it.

When group_deleted is true, the changes include a terminal group_deleted operation without customer_id. Apply all earlier operations in the batch before removing the local group. Delivery is at least once, so retries can repeat the same event_id. Pausing and reconnecting begins a new generation with sequence 1 and a fresh snapshot. Removing the connection deletes its queued and historical deliveries, although a request already in flight can complete.

Subscribe to these events to keep your integration in sync with customer groups. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.