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 Instances

Snapshots of a segment at a specific point in time. Each time a segment runs, it generates a segment instance representing the customers who matched the criteria on that 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 about 22 hours ago