Applies to: Customer Segments API | Customer Groups API | Customers API
Learn how to organize customer segments based on a set of filtered criteria.
A customer segment (also called a Smart Group) is a dynamic collection of customers who meet a set of filter criteria. While sellers can define the criteria for a segment, membership in the segment is dynamically adjusted based on the criteria. For example, a seller can create a "Visited more than 10 times" segment based on a "visits greater than 10" filter. The membership in the segment then updates dynamically as customers pass the threshold of 10 visits.
Note
Membership in customer groups behaves differently than membership in customer segments. Customers are explicitly added to customer groups by the seller or developer. For more information, see Customer Groups API.
You can use the Customer Segments API and Customers API to find or track basic information about the segments to which customers belong.
The Customer Segments API lets you view segment metadata. The following is an example customer segment:
{
"segment": {
"id": "8QJTJCE6AZSN6.LOYAL",
"name": "LOYAL",
"created_at": "2020-07-16T17:14:28.448Z",
"updated_at": "2023-01-19T22:28:27Z"
}
}Sellers define segments in the Square Dashboard or Square Point of Sale. Square APIs cannot be used to create or manage customer segment definitions or view segment criteria. To learn how sellers create customer segments, see Manage Customer Groups and Filters.
The Customers API lets you search for customers based on membership in up to three customer segments. If a customer belongs to one or more customer segments, the corresponding customer profile includes a segment_ids field that lists the IDs of the segments to which the customer belongs. This excerpt of a customer profile shows that the customer currently belongs to five segments:
{ "customer": { "id": "A537H7KAQWSAF8M8EM1Y23E16M", "created_at": "2021-10-28T20:19:07.692Z", "updated_at": "2022-10-14T17:52:14Z", ... "segment_ids": [ "8QJTJCE6AZSN6.LOYAL", "8QJTJCE6AZSN6.REACHABLE", "8QJTJCE6AZSN6.CARDS_ON_FILE", "gv2:8H24YRM74H2030XWJWP9F0MAEW", "gv2:4TR2NFVP8N63D9K1FZ5E62VD78" ], "version": 6 } }