If you build apps or custom integrations that rely on collection source conditions, the newest Shopify API release brings a breaking change you need to address right away. Starting with API version 2027‑01, the metafieldInteger condition type is removed from the GraphQL Admin API and replaced by metafieldInt. This shift aligns integer metafield handling with the Storefront API, but it also means any existing code that reads or writes metafieldInteger will start throwing validation errors. In this post we break down the change, explain who it impacts, and give you a clear migration path so your store or app stays functional.
What Changed
Shopify retired three GraphQL types that used the metafieldInteger suffix and introduced their metafieldInt counterparts:
• CollectionSourceInclusionConditionMetafieldInteger → CollectionSourceInclusionConditionMetafieldInt
• CollectionSourceInclusionConditionMetafieldIntegerRelation → CollectionSourceInclusionConditionMetafieldIntRelation
• Input fields metafieldInteger on CollectionSourceInclusionConditionInput and CollectionSourceInclusionConditionUpdateInput are now metafieldInt
The enum values that define the relation (EQUALS, GREATER_THAN, LESS_THAN) stay exactly the same. The only functional difference is the type of the value field. Where it used to be an Int, it is now a String. This mirrors the Storefront API’s Metafield.value field, which always returns a string representation of the underlying data.
Who Is Affected
Developers – Any app, script, or private integration that creates, updates, or reads collection source conditions using the GraphQL Admin API must update its schema. The change does not affect Liquid templates directly, but if you expose metafield‑driven collection rules through a storefront app, the underlying API calls will break.
Merchants – Most store owners won’t see anything on the front end until an app they rely on fails. However, if you’ve built custom collection rules via the Shopify admin UI (which uses the same API under the hood), those rules will stop working once the app’s API version is bumped to 2027‑01.
How to Update Your Queries and Mutations
The migration is a straightforward find‑and‑replace, but you must also convert every integer literal to a quoted string. Below are before‑and‑after examples for both writes (mutations) and reads (queries).
Write (mutation) example
graphql
# Before – using metafieldInteger
mutation CreateCollectionSource($conditions: [CollectionSourceInclusionConditionInput!]!) {
collectionCreate(source: {conditions: $conditions}) {
collection { id }
}
}
variables:
{
"conditions": [{
"metafieldInteger": {
"definitionId": "gid://shopify/MetafieldDefinition/1",
"relation": "GREATER_THAN",
"value": 2000
}
}]
}
graphql
# After – using metafieldInt (value as string)
mutation CreateCollectionSource($conditions: [CollectionSourceInclusionConditionInput!]!) {
collectionCreate(source: {conditions: $conditions}) {
collection { id }
}
}
variables:
{
"conditions": [{
"metafieldInt": {
"definitionId": "gid://shopify/MetafieldDefinition/1",
"relation": "GREATER_THAN",
"value": "2000"
}
}]
}
Read (query) example
graphql
# Before – fragment on the old type
query GetConditions($id: ID!) {
collection(id: $id) {
source {
... on CollectionSourceInclusionConditionMetafieldInteger {
relation
value
}
}
}
}
graphql
# After – fragment on the new type
query GetConditions($id: ID!) {
collection(id: $id) {
source {
... on CollectionSourceInclusionConditionMetafieldInt {
relation
value
}
}
}
}
Testing Before You Upgrade
Shopify lets you opt into the 2026‑10 version a few months early. In that version, metafieldInteger still exists, but the platform automatically resolves it to the new metafieldInt type when possible. Use this window to run your updated queries against a sandbox store or a duplicate of your production environment. Verify that:
value field as a string.If you encounter issues, double‑check that you haven’t missed any nested inputs (e.g., bulk updates or webhook payloads) that still reference metafieldInteger.
Action Checklist
metafieldInteger and replace it with metafieldInt.value field to a quoted string.CollectionSourceInclusionConditionMetafieldInt, etc.).Conclusion & Next Steps
The removal of metafieldInteger is a small but important change that aligns Shopify’s Admin and Storefront APIs around a single metafield value format. By updating your queries, mutations, and type definitions now, you’ll avoid painful runtime failures when the 2027‑01 version becomes the default. Keep an eye on Shopify’s developer changelog for future deprecations, and consider adding a version‑guard layer in your code to make future migrations smoother.
Need help auditing your app or testing the new schema? Reach out to the Shopify Partners community or drop a comment below – we’re happy to troubleshoot together.
