November 5, 2026 · 7 min read

Shopify API 2027-01 Breaking Changes: The Complete Developer Checklist

Shopify API 2027-01 ships January 1, 2027 with five hard breaking changes. This checklist covers every removal and the exact migration step for each one.

Shopify API 2027-01 Breaking Changes: The Complete Developer Checklist

Shopify API version 2027-01 becomes stable on January 1, 2027, and it carries the highest concentration of hard removals in a single quarterly release in recent memory. If your app or custom integration calls automaticDiscounts, writes line_item_id on a gift card, or deploys a checkout UI extension with undeclared metafield owner types, it will break or be blocked on that date. The fixes are mostly mechanical, but finding them in a large codebase before a holiday-season deadline is the real challenge.

Key takeaways

  • automaticDiscounts is fully removed from QueryRoot; replace it with discountNodes(query: "method:automatic") and regenerate all GraphQL types.
  • DiscountAutomaticConnection and DiscountAutomaticEdge also disappear, so any generated client code referencing those types breaks on 2027-01.
  • Gift card line_item_id becomes read-only in the REST Admin API; Shopify silently ignores the field on write rather than returning an error, which makes the bug harder to detect.
  • owner_type is now required on every metafield declaration in shopify.extension.toml; a missing field blocks the deploy outright.
  • Two additional removals land in the same version: metafieldInteger collection conditions and marketCurrencySettingsUpdate.

The timeline you are working against

2027-01 is currently in release-candidate status (the current latest stable is 2026-10). The release-candidate window is your last chance to test migrations without touching production traffic. API version 2026-01 retires on January 16, 2027, so any app still pinned there gets pushed forward into 2027-01 territory within days of the new stable dropping.

Shopify API versionRelease dateAccessible untilCurrent status
2026-10October 1, 2026October 16, 2027Latest stable
2027-01January 1, 2027January 16, 2028Release candidate
2026-01January 1, 2026January 16, 2027Retiring soon

The safest path: complete all migrations against 2026-10 (which already supports every replacement API), then do a clean version bump to 2027-01 before the January 1 cutover.

Breaking change 1: automaticDiscounts is removed from GraphQL Admin

automaticDiscounts no longer exists on QueryRoot in 2027-01. Any query that includes it fails validation immediately, returning an error instead of data. The companion automaticDiscountNodes query is also deprecated (though not yet removed in 2027-01, do not build anything new on it).

The replacement is discountNodes with a method:automatic filter:

# Before (fails on 2027-01)
query {
  automaticDiscounts(first: 10) {
    edges {
      node {
        ... on DiscountAutomaticBasic {
          title
          startsAt
        }
      }
    }
  }
}

# After (works on 2026-10 and 2027-01)
query {
  discountNodes(first: 10, query: "method:automatic") {
    edges {
      node {
        discount {
          ... on DiscountAutomaticBasic {
            title
            startsAt
          }
        }
      }
    }
  }
}

Notice that the inline fragments move one level deeper, onto the discount field of DiscountNode. That structural shift is what breaks auto-generated clients: DiscountAutomaticConnection and DiscountAutomaticEdge are both removed, so regenerating your types against the 2027-01 schema snapshot is not optional.

Migration checklist for this change:

  • Search your codebase (including generated files) for automaticDiscounts, DiscountAutomaticConnection, and DiscountAutomaticEdge.
  • Rewrite all matching queries to use discountNodes with query: "method:automatic".
  • Regenerate your GraphQL schema snapshot and client types against 2027-01.
  • If you cannot finish before January 1, pin to 2026-10 explicitly rather than relying on the unstable fallback.

Breaking change 2: Gift card line_item_id is read-only in REST

In REST Admin API version 2027-01, line_item_id on the Gift Card resource becomes read-only. Apps can still send the field on create or update requests, but Shopify will silently ignore it. The association between a gift card and its originating order line item is now managed exclusively by Shopify itself.

This silent-ignore behaviour is the dangerous part. Your integration will not get a 422 or a user error. It will get a 200 with the write simply discarded. The only way to verify the change had no effect is to read back the same gift card and confirm line_item_id did not change.

There is no replacement API for externally setting, replacing, or clearing that association. If your ERP or fulfilment system writes line_item_id to link gift cards to orders, that code path needs to be removed and the data model on your side updated accordingly.

Migration checklist for this change:

  • Search REST integration code for Gift Card create (POST /admin/api/.../gift_cards.json) and update (PUT /admin/api/.../gift_cards/{id}.json) calls that include line_item_id in the request body.
  • Remove the field from those payloads.
  • Add a read-back assertion in your test suite: create a gift card without line_item_id and confirm the response value matches what Shopify set natively.
  • Note that the REST Admin API has been designated a legacy system since October 1, 2024; any new gift card work should use the GraphQL Admin API.

Breaking change 3: owner_type required in extension metafield declarations

This one will silently sit in your TOML until the CLI refuses to deploy. Starting with API version 2026-10, Checkout and Customer Account UI extensions can include an owner_type on each metafield declaration in shopify.extension.toml. Starting with 2027-01, it is required, and the CLI blocks the deployment if any declaration is missing it.

The reason is performance: declaring the owner type lets checkout prefetch metafields only from the resource types the extension actually uses, rather than loading a broad set speculatively.

A valid declaration looks like this:

# shopify.extension.toml

[[extensions.metafields]]
namespace = "custom"
key       = "badge"
owner_type = "PRODUCT"

[[extensions.metafields]]
namespace = "custom"
key       = "note"
owner_type = "CUSTOMER"

The supported owner types for Checkout UI extensions are CART, COMPANY, CUSTOMER, PRODUCT, SHOP, and VARIANT (check the Shopify metafields glossary for type definitions if you need a refresher on what each owns). Note that COMPANY and CUSTOMER owner types require the protected customer data access declaration in your app.

If you read the same namespace/key combination from more than one resource type, you need a separate [[extensions.metafields]] block for each owner type. You cannot collapse them.

The fix is available on 2026-10 today. Add owner_type now, redeploy, and the 2027-01 upgrade becomes a one-line version bump instead of a blocked deploy during January peak.

Migration checklist for this change:

  • Open every shopify.extension.toml for checkout and customer account extensions.
  • Check both [[extensions.metafields]] and [[extensions.targeting.metafields]] blocks.
  • Add owner_type to every declaration. If the right type is not obvious (B2B checkouts using company location metafields are a common edge case), test on a development store running 2026-10 first.
  • Redeploy and confirm the CLI reports no validation warnings.

Two more removals in the same release

The changelog for 2027-01 is wider than the three headline changes. Two additional removals are worth flagging here.

metafieldInteger collection conditions removed. The metafieldInteger input and CollectionSourceInclusionConditionMetafieldInteger type are gone. The replacement is metafieldInt, and there is one non-obvious catch: the value field changes type from an Int literal to a String. So value: 2000 becomes value: "2000". The relation enums (EQUALS, GREATER_THAN, LESS_THAN) are unchanged. You can test metafieldInt on 2026-10 before cutting over.

marketCurrencySettingsUpdate mutation removed. Use marketCreate and marketUpdate to manage currency settings going forward. Any request that references the removed mutation on 2027-01 fails the entire operation, not just the offending field, because GraphQL validation rejects the whole request document.

Verification approach

Before bumping any app or integration to 2027-01, run through this sequence:

  1. Schema diff. Download the 2027-01 schema from the Shopify CLI (shopify app generate schema --api-version 2027-01) and diff it against your current schema snapshot. Every type or field your code references that is absent in the new schema is a migration target.
  2. Full-text search. Search for each removed symbol by name: automaticDiscounts, DiscountAutomaticConnection, DiscountAutomaticEdge, line_item_id, metafieldInteger, CollectionSourceInclusionConditionMetafieldInteger, marketCurrencySettingsUpdate.
  3. TOML audit. Grep every shopify.extension.toml for [[extensions.metafields]] and [[extensions.targeting.metafields]] blocks, then confirm each has owner_type.
  4. Staging run. Point a staging app at version 2027-01 and exercise every code path that touches discounts, gift cards, smart collections, markets, and checkout extensions. Watch for validation errors, not just HTTP 500s.
  5. Pin explicitly. If any migration is incomplete on January 1, 2027, pin that integration to 2026-10 explicitly. Do not rely on an unversioned or unstable endpoint.

I keep a 10,000+ SKU catalog running across multiple storefronts and the schema-diff step alone has caught version-upgrade regressions that manual search missed, particularly in generated Apollo or urql clients where the broken type reference is two layers removed from the query you wrote.

Conclusion

2027-01 is a release-candidate right now, which means you have weeks, not days, to test these migrations before they become mandatory. The changes are individually small but collectively dense, and three of the five affect different layers of the stack (GraphQL Admin, REST Admin, and extension TOML configuration). The safest strategy is to complete every migration against 2026-10 today, since all replacement APIs are already supported there, and treat the January 1 upgrade as a version string change rather than a migration event.

If you would rather hand this off, my studio Lintel offers Shopify API and ERP integrations.

shopifyapigraphqlbreaking-changescheckout-extensions

Frequently asked questions

What replaces the automaticDiscounts query in Shopify API 2027-01?

Use discountNodes with query: "method:automatic" instead. The key structural difference is that inline fragments on discount type now live on the discount field of DiscountNode, one level deeper than in the old automaticDiscounts response. You must also regenerate any auto-generated GraphQL client types, because DiscountAutomaticConnection and DiscountAutomaticEdge are removed in the same release.

Does Shopify return an error if you send line_item_id on a gift card REST request in 2027-01?

No. In REST Admin API version 2027-01, Shopify accepts create and update requests that include line_item_id but silently ignores the field. You will get a 200 response with the value unchanged from what Shopify set internally, so you must read back the gift card to verify the write had no effect.

Where do I add owner_type for metafield declarations in a Shopify checkout UI extension?

Add owner_type to each entry in [[extensions.metafields]] and [[extensions.targeting.metafields]] inside shopify.extension.toml. Valid values include CART, COMPANY, CUSTOMER, PRODUCT, SHOP, and VARIANT. If the same namespace and key apply to multiple resource types, create a separate declaration block for each owner type. The field is optional on 2026-10 and required (deploy-blocking if missing) on 2027-01.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn