Segmentation API now available

Retired Boards Appdev Customers Discounts And Orders

Topic summary

Shopify introduced a Segmentation API in the 2022-04 GraphQL Admin API version to help merchants target specific customer groups for marketing, analytics, and reporting.

Key Changes:

  • Saved searches and discount eligibility based on saved searches are being deprecated
  • Apps currently using saved searches must migrate to the Segmentation API
  • Segments are groups of customers meeting specific criteria (e.g., purchased a particular product)

January 2023 Update (API version 2023-01):

  • Breaking change: Some queries now process asynchronously based on complexity and data volume
  • Most queries remain synchronous, but async queries typically resolve within 5 seconds (some may take 1-2 minutes or longer)
  • Apps must handle error codes for queries requiring async processing

Action Required:
Developers should review where their apps use saved search resources and update to use Segmentation API queries and mutations. Migration guides and documentation are available to support the transition.

Summarized with AI on November 24. AI used: claude-sonnet-4-5-20250929.
1

In the 2022-04 API version release, Shopify is introducing a Segmentation API for the GraphQL Admin. The API helps app partners support merchants that want to target specific customer groups for marketing, analytics, and reporting. Saved searches and Discount Eligibility based on saved searches, will be deprecated in favor of the Segmentation API. If your app uses saved searches, then you need to migrate your app to support segments.

Updating your app to support segments

If you want your app to support segments, then you’ll need to update your app to use the Segmentation API. Review where your app uses a saved search resource and update your apps to use the queries and mutations illustrated in the GraphQL Admin API reference pages. For example, you can use the segmentMigration object to retrieve the segment ID that corresponds to a saved search ID.

How segments work

A segment is a group of 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.

For more information on how to update your app, visit our developer documentation.

1 Like
2

Update:

Starting in January 2023, on the 2023-01 API release, some queries could be processed and returned asynchronously based on complexity and the amount of shop data. Most queries will continue to be evaluated synchronously. This breaking change allows you to build the best possible user experience as we introduce more complex filters in Segmentation. Async queries should revolve within 5 seconds but some queries might take up to 1-2 minutes or even longer.

To get up to date, make sure you are handling responses returning an error code because the query must be processed asynchronously. You can follow our migration guide.

Learn more about building for asynchronous queries in our developer documentation or visit our API forum for questions.