Manage customer segments
You can use the GraphQL Admin API to manage customer segments. This guide shows you how to create, retrieve, update, and delete customer segments.
RequirementsAnchor link to section titled "Requirements"
- The store you're working with has customer saved searches and customers.
- 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: Create a segmentAnchor link to section titled "Step 1: Create a segment"
To create a new segment, use the
segmentCreate mutation, and specify the name and query of the segment as arguments. In the following example, the query specifies customers that have subscribed to email marketing:
Step 2: Retrieve customer segmentsAnchor link to section titled "Step 2: Retrieve customer segments"
You can retrieve a list of customer segments from a shop by querying
segments. In the following example, the response body returns the first segment, including the segment’s ID and name, and whether the segment is a default that was created by Shopify. The query also includes cursor and pagination information.
The query in the response body includes a combination of conditions on facts about the segment. In this case, the segment query specifies customers that have subscribed to email marketing.
Query an individual segmentAnchor link to section titled "Query an individual segment"
To query an individual segment, query the
segment object and pass the segment ID as an argument:
Query a list of segment membersAnchor link to section titled "Query a list of segment members"
To retrieve a list of members associated with an individual segment, use the
customerSegmentMembers query, and pass in the segment attribute and conditions. You can query a maximum of 250 segments. The maximum value that
last arguments accept is
The following example shows how to retrieve a list of segment members that aren't subscribed to email communications. The first member of the segment is returned, including their customer ID, first name, last name, and default email address. Additional attribute statistics are also returned, including the member's total number of orders from the store and the average amount spent.
As of version 2023-01 of the GraphQL Admin API, the most complex queries might be processed asynchronously. You can migrate your app to support async queries.
Step 3: Retrieve segment filtersAnchor link to section titled "Step 3: Retrieve segment filters"
You can use the
segmentFilters query to retrieve a list of filters (attributes) added to segment queries. In the following example, the first two segment filters are returned, including a human-readable, localized name for the filter and the filter name in ShopifyQL.
Query segment filter suggestionsAnchor link to section titled "Query segment filter suggestions"
You can use the
segmentFilterSuggestions query to retrieve a list of filter suggestions associated with a segment:
Query segment value suggestionsAnchor link to section titled "Query segment value suggestions"
You can use the
segmentValueSuggestions query to retrieve a list of value suggestions associated with a segment:
Step 4: Apply a discount to a customer segmentAnchor link to section titled "Step 4: Apply a discount to a customer segment"
After you've retrieved a list of segments from the store, you can use a code discount mutation to specify which
segmentId you want to apply a discount to.
The following example shows how to use the
discountCodeBasicCreate mutation to apply a 10%-off all items discount, named "Discount", to two customer segments:
Step 5: Update a segmentAnchor link to section titled "Step 5: Update a segment"
To update an existing segment, use the
segmentUpdate mutation, and specify the
id of the
segment you that you want to update:
Step 6: Delete a segment (optional)Anchor link to section titled "Step 6: Delete a segment (optional)"
To permanently remove a segment from a shop, use the
segmentDelete mutation, and specify the
id of the
segment that you want to delete:
- Migrate from saved searches to customer segments.