Summary
The products_purchased MATCHES (id = X) syntax works correctly when creating segments via the Shopify Admin UI, but fails with “‘MATCHES’ is
unexpected” error when using the segmentCreate GraphQL mutation. This appears to be a discrepancy between the Admin UI and the public GraphQL API.
Environment
- API Version: 2026-01
- Endpoint: GraphQL Admin API
- Mutation: segmentCreate
What Works (Admin UI)
Creating a segment in the Shopify Admin with this query succeeds:
FROM customers
SHOW customer_name, note, email_subscription_status, location, orders, amount_spent
WHERE last_order_date BETWEEN -32d AND -30d
AND number_of_orders BETWEEN 1 AND 2
AND products_purchased MATCHES (
id = 9847762092347
)
ORDER BY updated_at
The segment is created successfully and filters customers as expected.
What Fails (GraphQL API)
Using the segmentCreate mutation with the equivalent WHERE clause fails:
Mutation:
mutation CreateSegment($name: String!, $query: String!) {
segmentCreate(name: $name, query: $query) {
segment {
id
name
query
}
userErrors {
field
message
}
}
}
Variables:
{
“name”: “Test”,
“query”: “last_order_date BETWEEN -32d AND -30d AND number_of_orders BETWEEN 1 AND 2 AND products_purchased MATCHES (id = 9847762092347)”
}
Response:
{
“data”: {
“segmentCreate”: {
“segment”: null,
“userErrors”: [
{
“field”: [“query”],
“message”: “Query Line 1 Column 79: ‘MATCHES’ is unexpected.”
}
]
}
}
}
Variations Tested
All of the following fail with the same “‘MATCHES’ is unexpected” error:
- products_purchased MATCHES (id = 9847762092347)
- products_purchased MATCHES (id IN (9847762092347))
- Multi-line formatting matching Admin UI
- products_purchased MATCHES as standalone clause (no AND)
What Does Work via API
Simpler queries without products_purchased MATCHES succeed:
{
“name”: “Test Without Product Filter”,
“query”: “last_order_date BETWEEN -32d AND -30d AND number_of_orders BETWEEN 1 AND 2”
}
This creates the segment successfully.
Documentation Reference
The Segment query language reference clearly documents the MATCHES syntax for function attributes:
Functions names are followed by either MATCHES or NOT MATCHES and parentheses enclosing the list of optional parameters.
And specifically for products_purchased:
products_purchased MATCHES (id = 2012162031638)
products_purchased MATCHES (tag = ‘Sports wear’)
products_purchased MATCHES (id IN (2012162031638, 1012132033639))
Questions
- Is MATCHES operator support for segmentCreate planned or currently in development?
- Is there an alternative API or approach to create segments with product purchase filters?
- Is this a known limitation or a bug?
Any guidance would be appreciated!
