Create a Shopify customer segment using the segmentCreate Admin GraphQL mutation with a ShopifyQL segment query
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
Determine the ShopifyQL query string that defines your segment — e.g., `email_subscription_status = 'SUBSCRIBED' AND customer_tags CONTAINS 'vip'`; use the segment editor in the Shopify admin to validate query syntax before using it via API
Call `segmentCreate(name: "VIP Email Subscribers", query: "email_subscription_status = 'SUBSCRIBED' AND customer_tags CONTAINS 'vip'")` using the Admin GraphQL API with `write_customers` access scope
Inspect the returned `segment.id` and `segment.name`; the segment is immediately saved but customer membership is computed asynchronously by Shopify
Query segment membership with `customerSegmentMembersQueryCreate(segmentId: $segmentId, query: "")` to trigger a members query, then poll `customerSegmentMembers` with the returned `queryId` to retrieve the matched customers
Update the segment query at any time with `segmentUpdate(id: $segmentId, name: $name, query: $newQuery)` — Shopify re-evaluates membership after each update
Use segment IDs in marketing automation (e.g., Flow triggers, bulk email) by referencing the segment in the relevant app's integration
Known gotchas
The `products_purchased MATCHES` operator syntax works in the Shopify admin segment editor but has known inconsistencies when used via the segmentCreate API mutation — test your query string via the admin editor first and avoid using MATCHES with product IDs in the API if you encounter parse errors
Segment member counts are not returned synchronously with segmentCreate — membership is computed in the background; do not rely on instant counts for time-sensitive operations
segmentCreate requires `write_customers` scope; read-only customer scopes allow listing segments but not creating or modifying them
Give your agent this knowledge — and 15,600+ 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?