Customer segments
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 work
Anchor link to section titled "How segments work"
A segment is a group of members (commonly customers) that meet specific criteria. Segments enable users 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 user could then send a targeted email to the members of that segment.
Segment members can belong to multiple segments.
Anatomy of a segment
Anchor 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 segments
Anchor 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 migrated
Anchor 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 SegmentMigrations.
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:
| Event | What happens |
|---|---|
| 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 searches
Anchor 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.
Limitations
Anchor 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
firstandlastarguments accept is250.You can only manage segments using the GraphQL Admin API. Segments aren't supported in the REST Admin API.
- Build a customer segment template extension.
- Build a customer segment action extension.
- Learn how to manage customer segments.
- Migrate from saved searches to customer segments.