Segmentation is the process of using criteria to separate data into smaller groups. The GraphQL Admin API enables you to filter out specific customers for marketing, analytics, and reporting purposes.
This guide describes what segmentation is, its relationships, and some considerations before you get started.
How segments workAnchor link to section titled "How segments work"
A segment is a group of members (commonly customers) that meet specific criteria. Merchants can use segments to conduct marketing activities, access information that helps to inform a business decision, or learn more about certain segment member behaviors.
For example, a segment might include members that bought a particular product. A merchant could use the segment to take action by sending a targeted email message to the group members.
Segment members can belong to multiple segments.
Anatomy of a segmentAnchor link to section titled "Anatomy of a segment"
Each segment contains a query argument, or a precise definition of the segment, indicating the condition or conditions that data must satisfy to be selected. Query arguments act as segment filters.
For example, a query can specify segment members that have left a checkout without completing their purchase in the last 30 days. For more information, refer to the query syntax reference.
Migrating to customer segmentsAnchor link to section titled "Migrating to customer segments"
To ease the migration from using
customerSavedSearches to customer
segments, a list of customer segment IDs is automatically created from existing
customerSavedSearches. If a
customerSavedSearch is unmigratable, then
segments aren't created for it.
Segments aren't backwards-compatible or connected to saved searches. For example, if a merchant creates or updates new segments, and you haven’t migrated your app to use segments instead of saved searches, then your app won't synchronize the changes that the merchant is making to segments.
Behavior of apps that aren't migratedAnchor link to section titled "Behavior of apps that aren't migrated"
In API versions older than
2022-04, you can continue to create, update, and delete saved searches using the deprecated elements. If a customer saved search is compatible, then Shopify converts saved searches in the backend to segments. You can verify whether a saved search was successfully translated to a segment by querying
When a merchant or app updates or deletes a saved search, Shopify attempts to translate the saved search to a segment in the following ways:
|The saved search is updated and can be converted to a segment.||
|The saved search is updated but can't be converted to a segment.||
The saved search is deleted.
Only the grouping of members (customers) is deleted. Customer data is preserved.
The saved search is updated or deleted.
When a segment is updated or deleted, it syncs its associated saved search.
Validation behavior of saved searchesAnchor link to section titled "Validation behavior of saved searches"
Validations are introduced as part of the migration from using saved searches to segments.
API requests that involve price rules, discount codes, and saved searches are validated. Validations either allow API requests, or block API requests, returning an error. Unmigratable saved searches are blocked.
Validation occurs under the following conditions:
- Price rules or discount codes are created or updated.
- A saved search that's used in a price rule or a discount code is updated.
LimitationsAnchor link to section titled "Limitations"
- A segment can only include members from a single shop.
You can query a maximum of 250 segments. The maximum value that
lastarguments accept is
You can only manage segments using the GraphQL Admin API. Segments aren't supported in the REST Admin API.