Query Shopify customer segments programmatically via Admin GraphQL
domain: shopify.dev · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Query the list of segments using the `segments` Admin GraphQL query, which returns segment `id`, `name`, `query` (the ShopifyQL condition string), and `creationDate`.
To create a new segment, call the `segmentCreate` mutation with a `name` and a `query` string written in ShopifyQL syntax (e.g., `customer_tags CONTAINS 'vip'`).
Retrieve the members of a segment using the `customerSegmentMembers` query, passing the segment's `id`; paginate with `first` and `after` cursor arguments.
Use the `segmentFilters` query to discover available ShopifyQL filter attributes (e.g., `number_of_orders`, `total_spent`, `customer_tags`) to build valid query strings programmatically.
To count members without fetching full records, query `customerSegmentMembersCount` with the segment ID; this is more efficient for analytics dashboards.
Subscribe to segment membership changes by listening to relevant customer webhooks (`customers/update`) and re-evaluating segment overlap on the application side, as Shopify does not emit segment-membership-change webhooks.
Known gotchas
ShopifyQL segment query strings have their own syntax distinct from GraphQL; a syntactically invalid ShopifyQL string will cause `segmentCreate` to return a user error, not a GraphQL error.
The `customerSegmentMembers` query is eventually consistent — segment membership may lag by minutes after a qualifying customer action (e.g., a purchase that crosses a spend threshold).
Segments are shop-level constructs, not app-level; a segment created by your app is visible and editable by merchants in the Shopify admin, and merchants can modify or delete it independently of your app.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?