7 min read
Shopify API 2026-10: What Changed for Metafield Filtering
Shopify API 2026-10 is now the latest stable version. See what changed for metafield filtering and run this QA checklist before you call the upgrade done.
Shopify's Admin GraphQL API version 2026-10 is now the latest stable release, out since October 1, 2026.
From this version on, a GraphQL query that filters by a metafield that isn't set up correctly for filtering returns an error instead of silently returning misleading results.
This guide covers what changed, why it matters, and a QA checklist if you're upgrading now.
What Changed in API 2026-10
The Admin GraphQL API now validates metafield filters before running a query. A metafield filter fails when the metafield has no definition, the definition isn't configured to allow filtering, or the metafield type doesn't support the filter or comparison used.
Before 2026-10, an invalid predicate could be silently ignored, so a query could appear to work while returning results that didn't reflect the intended filter.
Shopify announced the change in its developer changelog, and 2026-10 is now the version new app builds target by default.
Queries on 2026-07 and earlier keep the old behavior until they're upgraded.
Why Metafield Definitions Matter
A metafield definition sets the structure and rules for metafields that share a namespace and key, including data type, validation, access settings, and supported capabilities.
One capability, adminFilterable, controls whether a metafield's values can be used to filter products, companies, company locations, metaobjects, or orders in the Admin and GraphQL Admin API.
Shopify's own metafield definitions documentation notes limits regardless of this setting: JSON and rich-text metafields aren't Admin Filterable.
Two Other Changes That Touch the Same Definitions
- Customer Account API: since June 16, 2026, app-resource metafields need a definition and the right customer account permissions to be readable through the Customer Account API. Metafields owned by Customer or Order resources aren't affected by this one.
- Shopify Events: since July 2026, apps can subscribe to metafield changes on Product, Order, Customer, Collection, and Location, but Shopify's own examples still set api_version to "unstable" for this, so treat it as a developer preview, not a stable production feature.
QA Checklist If You're Moving to 2026-10 Now
- Find every GraphQL Admin API query in your app that filters by a metafield.
- Confirm each filtered metafield has a definition with the correct owner type, namespace, key, and data type.
- Check that adminFilterable is turned on where required, and that the field type supports the filter or comparison you use.
- Run the affected queries against API 2026-10 and confirm they return the expected results instead of a filtering error.
- If you read app-resource metafields through the Customer Account API, confirm the definitions and access settings are in place.
- Record which app or team owns each metafield, and flag duplicate or legacy fields before you change the schema.
If Queries Already Started Failing
A query that used to return results and now returns a filtering error on 2026-10 is doing what Shopify intends: the predicate was never valid, it was just ignored before.
Fix the metafield definition or the filter itself rather than staying on an older API version, since older versions are retired on Shopify's usual rolling schedule.
Summary
API 2026-10 is live. From this version on, an invalid metafield filter in the GraphQL Admin API returns an error instead of a silently wrong result. Check your filtered queries' metafield definitions, confirm adminFilterable where it's needed, and test against 2026-10 before you treat the upgrade as done.
Frequently Asked Questions
Is Shopify API version 2026-10 released?
Yes. It has been the latest stable version since its October 1, 2026 release; 2027-01 is the next release candidate.
Why does my metafield filter query return an error on API 2026-10?
Because the metafield used in the filter has no definition, the definition doesn't allow filtering, or the metafield type doesn't support the comparison used. Earlier API versions ignored this instead of returning an error.
What is adminFilterable?
A metafield definition capability that allows a metafield's values to be used when filtering supported resources (products, companies, company locations, metaobjects, and orders) in the Admin and GraphQL Admin API.
Are JSON and rich-text metafields filterable?
No. Shopify's documentation states Admin Filterable isn't available for JSON or rich-text metafield types, regardless of other settings.
Can I stay on an older API version to avoid this change?
Only temporarily. Queries on 2026-07 and earlier keep the old behavior until they're upgraded, but older versions are retired on Shopify's usual schedule, so this delays the change rather than avoiding it.