List the customers in a segment
Page through the members of a customer segment with customerSegmentMembers, or run an ad hoc segment query with customerSegmentMembersQueryCreate.
- API
- Admin GraphQL API
- Operations
- customerSegmentMembers, customerSegmentMembersQueryCreate, customerSegmentMembersQuery
- Access scope
- read_customers
- API version
- 2026-10
- Last checked
In short
To list the customers in a segment, query customerSegmentMembers with the segmentId and page with first and after; totalCount gives the size. To test a segment query without saving it, start customerSegmentMembersQueryCreate with a ShopifyQL condition such as number_of_orders >= 3, wait until done is true, then pass its ID as queryId to customerSegmentMembers. Both need read_customers.
How to use it
- Find the segment ID with the segments query, which lists each segment’s name and query.
- Send SegmentMembers with first: 100 and page with after: endCursor while hasNextPage is true.
- For an unsaved condition, send StartMembersQuery, poll customerSegmentMembersQuery(id) until done, then query customerSegmentMembers(queryId: …).
- Use the member IDs to tag customers, send codes or export to your email tool.
Code
segment-members.graphqlquery SegmentMembers($segmentId: ID!, $first: Int!, $after: String) {
customerSegmentMembers(segmentId: $segmentId, first: $first, after: $after) {
totalCount
edges {
node {
id
displayName
numberOfOrders
amountSpent {
amount
currencyCode
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
segment-members.variables.json{
"segmentId": "gid://shopify/Segment/1234567890",
"first": 100,
"after": null
}
segment-members.response.json{
"data": {
"customerSegmentMembers": {
"totalCount": 1842,
"edges": [
{
"node": {
"id": "gid://shopify/CustomerSegmentMember/1111111111",
"displayName": "Ada Example",
"numberOfOrders": "7",
"amountSpent": {
"amount": "642.50",
"currencyCode": "EUR"
}
}
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "eyJsYXN0X2lkIjoxMTExMTExMTExfQ=="
}
}
}
}
members-query-create.graphqlmutation StartMembersQuery($input: CustomerSegmentMembersQueryInput!) {
customerSegmentMembersQueryCreate(input: $input) {
customerSegmentMembersQuery {
id
done
currentCount
}
userErrors {
code
field
message
}
}
}
members-query-create.variables.json{
"input": {
"query": "number_of_orders >= 3 AND email_subscription_status = 'SUBSCRIBED'"
}
}
members-query-create.response.json{
"data": {
"customerSegmentMembersQueryCreate": {
"customerSegmentMembersQuery": {
"id": "gid://shopify/CustomerSegmentMembersQuery/1234567890",
"done": false,
"currentCount": 0
},
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- The connection has edges, not nodes: read edges[].node.
- Segment queries use Shopify’s segment query language, not the admin search syntax.
- Contact fields such as email and phone are protected customer data; request access before selecting them.
- numberOfOrders is an UnsignedInt64 and comes back as a string.
Questions
- How do I export a Shopify customer segment with the API?
- Page through customerSegmentMembers with the segment ID and write each member to your file or tool.
- Can I run a segment query without saving a segment?
- Yes. customerSegmentMembersQueryCreate runs a condition asynchronously; pass its ID as queryId when it is done.
- Which scope do segment queries need?
- read_customers. Writing segments with segmentCreate needs write_customers.
Shopify documentation
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
