Segments

Customer segmentation: rules, membership, exports and analytics

📄️ Create a segment

Creates a new customer or product segment for the store. Rules follow the segment rule DSL (nested AND/OR/NOT groups of field conditions).

📄️ List segments

Returns a paginated list of the store's segments, each enriched with rolling 30-day performance metrics. Supports filtering by type, status and free-text search.

📄️ List segment export jobs

Returns a paginated list of segment export jobs for the store, optionally filtered by segment and job status.

📄️ Get export job status

Returns a single segment export job with its progress (including a computed completion percentage), result and error details.

📄️ List field option values

Returns distinct values (with product counts) for a product attribute field, for use as rule-condition value suggestions. Only `category` and `vendor` are supported; results are capped at 50 values.

📄️ Get a segment

Returns a single segment by ID.

📄️ Update a segment

Partially updates a segment. At least one field is required. Auto-generated segments cannot be edited (403).

📄️ Archive a segment

Soft-deletes a segment by archiving it. Auto-generated segments cannot be deleted (403).

📄️ Activate a segment

Transitions a segment to `active` status and triggers membership evaluation. Returns 400 if the segment is already active.

📄️ Pause a segment

Transitions a segment to `paused` status, stopping automatic membership refreshes. Returns 400 if the segment is already paused; auto-generated segments cannot be paused (403).

📄️ Refresh segment membership

Synchronously re-evaluates the segment's rules against the member population and updates the cached membership.

📄️ Preview segment membership

Evaluates a rule set against a random sample of up to 1000 members and returns an extrapolated size estimate plus up to 10 sample members. Results are cached briefly per (type, rules).

📄️ List segment members

Returns the segment's current members (customers or products depending on segment type) with their attribute/metric data, using offset-based pagination and optional search.

📄️ Get segment membership history

Returns daily membership additions/removals for the segment over the requested trailing window (default 30 days).

📄️ Explain membership for a member

Evaluates the segment's rules against a specific member and returns a per-condition explanation of why the member does or does not match, plus whether the member is currently tracked in the cached membership.

📄️ Export a segment

Starts an asynchronous export of the segment's members to a CSV file or an ad-platform audience (Meta, TikTok, Snap). Returns the created job; poll `GET /segments/exports/{jobId}` for progress.

📄️ Segment analytics overview

Returns revenue/order KPIs for the segment's members over a date range (default trailing 30 days), optionally compared against the preceding period of equal length.

📄️ Segment geographic distribution

Returns the geographic distribution of the segment's members grouped by country and by governorate/state. Note that `start_date`/`end_date` are accepted but not currently applied by the handler.

📄️ Top products for a segment

Returns the top products purchased by the segment's members over a date range (default trailing 30 days), sortable by revenue, units or orders.

📄️ Top categories for a segment

Returns the top product categories purchased by the segment's members over a date range (default trailing 30 days), with revenue share percentages.