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.
Anchor to RequirementsRequirements
- 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
read_customers
andwrite_customers
access scopes. Learn how to configure your access scopes using Shopify CLI.
Anchor to Step 1: Create a segmentStep 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:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL mutation
JSON response
Anchor to Step 2: Retrieve customer segmentsStep 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.
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Query an individual segmentQuery an individual segment
To query an individual segment, query the segment
object and pass the segment ID as an argument:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Query a list of segment membersQuery 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 first
and last
arguments accept is 250
.
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.
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Step 3: Retrieve segment filtersStep 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.
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Query segment filter suggestionsQuery segment filter suggestions
You can use the segmentFilterSuggestions
query to retrieve a list of filter suggestions associated with a segment:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Query segment value suggestionsQuery segment value suggestions
You can use the segmentValueSuggestions
query to retrieve a list of value suggestions associated with a segment:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Step 4: Apply a discount to a customer segmentStep 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:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL Mutation
JSON response
Anchor to Step 5: Update a segmentStep 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:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL mutation
JSON response
Anchor to Step 6 (Optional): Delete a segmentStep 6 (Optional): Delete a segment
To permanently remove a segment from a shop, use the segmentDelete
mutation, and specify the id
of the segment
that you want to delete:
POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
GraphQL mutation
JSON response
Anchor to Next stepsNext steps
- Migrate from saved searches to customer segments.