Migrate saved searches to customer segments
In API version 2022-04, we introduced the
Segment object in the GraphQL Admin API, which you can use to filter out specific customers for marketing, analytics, and reporting purposes.
As of API version 2022-04, saved searches and discounts applied to saved searches are deprecated in the GraphQL Admin API. These changes affect all merchants because all stores have built-in, default saved searches.
This guide shows you how to migrate your app from using saved searches to customer segments.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_customersaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
Step 1: Determine if your app is affectedAnchor link to section titled "Step 1: Determine if your app is affected"
Your app is affected if it uses any deprecated GraphQL Admin API types and fields or REST Admin API resources.
To determine whether your store is using customer saved searches, you can make a request to the GraphQL Admin API. The following example shows how to retrieve the first 250 customer saved searches:
REST Admin APIAnchor link to section titled "REST Admin API"
If you're using the REST Admin API, then, you can use the
GET customer_saved_searches endpoint to retrieve a list of customer saved searches for a store. The following example shows how to retrieve a list of customer saved searches:
This section describes deprecated GraphQL API types and fields and their replacements, changes to existing GraphQL Admin API types and fields, and recommended mutations for creating and modifying discount codes.
Deprecated typesAnchor link to section titled "Deprecated types"
The following types were removed from the GraphQL Admin API:
Use the following elements instead:
Deprecated fieldsAnchor link to section titled "Deprecated fields"
The following fields were removed from the GraphQL Admin API:
savedSearchesfield from the
savedSearchesIdsfield from the
Use the following fields instead:
segmentsfield from the
segmentIdsfield from the
Recommended mutations for creating and modifying discount codesAnchor link to section titled "Recommended mutations for creating and modifying discount codes"
You can use the Discounts API to create and update discount codes for all customers or for specific customers. You can specify which customers can use which discount codes by using the GraphQL Admin API to filter out customers based on specific attributes.
The following mutations enable you to create or modify the following discount codes:
prerequisite_saved_search_ids property from the
PriceRule resource in the REST Admin API is deprecated. Use the
customer_segment_prerequisite_ids from the
PriceRule resource instead.
The following table lists the resources that are affected by the REST Admin API saved searches deprecation:
Step 2: Determine whether you have unmigratable saved searchesAnchor link to section titled "Step 2: Determine whether you have unmigratable saved searches"
The following types of saved searches are unmigratable if they create or update price rules or discount codes:
- Free text
- Saved searches that contain more than five filters
Unmigratable saved searches are blocked by the API validation and return an error. If an API request is blocked, then the price rule or discount code isn't affected.
If a saved search is updated, causing it to match the unmigratable saved search criteria, and that saved search is referenced by a price rule or a discount code, then the API request is blocked, and an error message is returned.
The following mutations are blocked if they use unmigratable saved searches:
Step 3: Retrieve segment migrationsAnchor link to section titled "Step 3: Retrieve segment migrations"
To determine which saved search corresponds to which segment, you can query
SegmentMigrations. For example, use the
segmentMigrations query to retrieve the segment ID that corresponds to a saved search ID.
The following example shows how to retrieve the first three segment migrations:
Step 4: Update your app to support segmentsAnchor link to section titled "Step 4: Update your app to support segments"
If you want your app to support segments, then you can change your app to use the queries and mutations that are described in the Manage customer segments guide.
- Learn how to manage customer segments.