Customer Segmentation Table (BETA)

customer_segmentation_table

The Customer Segmentation table provides a complete list of customers included in each segment instance, along with metadata about the segment, when it was created, and how it was defined. Querying this table allows you to identify which customers belong to which segments at any given point in time, measure list composition, and join against other tables to analyze performance. Learn more about customer retention and customer segmentation.

🚧
Key Concepts
Segment

A collection of customers that meet a defined set of rules or criteria. Segments are created by users to group customers based on behaviors, attributes, or activities.

Segment Instance

A snapshot of a segment at a specific point in time. Each time a segment runs on its schedule (once a day or once every other day), it generates a segment instance representing the customers who matched the criteria on that date.

Usage Notes

Joins to other tables are supported by customer_id.

To match query results with the Customer Segments interface, filter for the most recent segment instance per segment. Without this, queries will include all historical instances and totals will appear inflated relative to analytics in the UI.

Relationship to Other Tables
The Customer Segmentation table is a membership list that can be joined with other tables to analyze segment behavior.

Customers — join on customer_id to add profile data (e.g. name, email, address, consent, tags).

Orders — join on customer_id to analyze purchase behavior (e.g. order counts, revenue, new vs. returning).

Pixel Orders — join on customer_id to evaluate attribution and ad-driven activity at the order level.

Customer Segmentation Analytics — join on customer_id and align the snapshot via segment_id + instance_event_date to access pre-aggregated metrics around a pinned_event_date.

Dimensions

Dimensions are immutable properties that can be used for grouping data.

Title	ID	Type	Description
Customer Identity	`customer_identity`	string	The identity of the customer in the segment. Can be either `email` or `customer_id` type. Example values: `[email protected]`, `5209503793328`
Instance Created Date	`instance_created_date`	date	The timestamp when the segment instance (run/snapshot) was generated. Example value: `2025-08-25 11:08:39`
Schedule	`schedule`	string	The recurring schedule for running the segment. Example values: `once_a_day`, `once_every_other_day`
Segment By	`segment_by`	string	The audience type used to group customers in the segment. Example value: `customer_id`, `email`
Segment Created Date	`segment_created_date`	date	The date when the segment was originally created. Example value: `2023-07-20 08:33:08`
Segment ID	`segment_id`	string	The unique identifier for a segment. Example value: `64b8f144256b30501b2ea1e0`
Segment Instance ID	`segment_instance_id`	string	The unique identifier for a specific segment instance (run/snapshot). Example value: `64b8f144256b30501b2ea1e0_2025_08_25`
Segment Name	`segment_name`	string	The human-readable name of the segment, Example values: `Fourth of July Sale`, `At least 3 orders`, `Jan Non Recent Active`

Measures

Measures are numeric fields that can be aggregated and/or combined to calculate new metrics.

Title	ID	Type	Description
Number of Customers	`num_of_customers`	numeric	The total number of unique customers included in the segment instance.
Number of Orders	`num_of_orders`	numeric	The total number of orders placed by customers in the segment during the relevant time window.
Total Revenue	`total_revenue`	numeric	The total revenue generated by customers in the segment during the relevant time window.

Updated 17 days ago