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
<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/segmentation/segment-flow-199c432bc6f09cca0e45052022c042ac976ca7c28cf6ce694b82a4f7c5b41042.png" class="lazyload" alt="A diagram showing the relationship between a segment, segment member, and shop" width="90%" height="269"></figure>
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
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](/docs/api/shopifyql).
## Migrating to customer segments
> Caution:
> Segmentation is a breaking change that replaces the GraphQL Admin API [SavedSearch](/docs/api/admin-graphql/latest/objects/savedsearch#top) object. If your app uses saved searches, then you need to [migrate](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches) your app to support 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](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches#step-2-determine-whether-you-have-unmigratable-saved-searches), 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
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](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches), 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`](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches#step-3-retrieve-segment-migrations).
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:
<table>
<caption>How Shopify attempts to translate a saved search to a segment</caption>
<tr>
<th scope="col">Event</th>
<th scope="col">What happens</th>
</tr>
<tr>
<td>The saved search is updated and can be converted to a segment.</td>
<td>
<ul>
<li><b>If the segment exists</b>: The segment is updated.</li>
<li><b>If the segment doesn't exist</b>: A new segment is created.</li>
</ul>
</td>
</tr>
<tr>
<td>The saved search is updated but can't be converted to a segment.</td>
<td>
<ul>
<li><b>If the segment exists</b>: The segment is deleted.</li>
<li><b>If the segment doesn't exist</b>: Nothing.</li>
</ul>
</td>
</tr>
<tr>
<td><p>The saved search is deleted.</p><p>Only the grouping of members (customers) is deleted. Customer data is preserved.</p></td>
<td>
<ul>
<li><b>If the segment exists</b>: The segment is deleted.</li>
<li><b>If the segment doesn't exist</b>: Nothing.</li>
</ul>
</td>
</tr>
<tr>
<td><p>The saved search is updated or deleted.</p><p>When a segment is updated or deleted, it syncs its associated saved search.</p></td>
<td>
<ul>
<li>The migration table is updated to set the <code>segment_id</code> of the associated saved search to <code>nil</code>.</li>
<li>If the saved search is updated in the future, a new segment might be created if the saved search can be converted.</li>
</ul>
</td>
</tr>
</table>
### 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](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches#step-2-determine-whether-you-have-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
- A segment can only include members from a single shop.
- You can query a maximum of 250 segments. The maximum value that `first` and `last` arguments accept is `250`.
## Next steps
- Build a [customer segment template extension](/docs/apps/build/marketing-analytics/customer-segments/build-a-template-extension).
- Build a [customer segment action extension](/docs/apps/build/marketing-analytics/customer-segments/build-an-action-extension).
- Learn how to [manage customer segments](/docs/apps/build/marketing-analytics/customer-segments/manage).
- Migrate from [saved searches to customer segments](/docs/apps/build/marketing-analytics/customer-segments/migrate-saved-searches).