Shopify Storefront API: What's Changed and What You Must Act On

The Shopify Storefront API is a public-facing GraphQL API that lets developers build fully custom shopping experiences on any platform, from headless storefronts to mobile apps and AI agents. In 2026 it has moved faster than any prior year: version 2026-04 is the current stable release, 2026-07 ships as a release candidate today (June 30, 2026) with breaking changes, and the 2024-10 version sunsets in October, giving teams a five-month runway to migrate. If your headless store is not on a supported version right now, the clock is already running.

Key takeaways

• 2026-04 is the current stable Storefront API version; 2026-07 is the active release candidate with breaking cart and product query changes.
• The legacy 2024-10 version sunsets in October 2026, custom builds face remediation costs of $8,000, $40,000 if left too late.
• Version 2025-10 introduced the visitorConsent parameter on the @inContext directive, encoding GDPR/privacy consent directly into the checkout URL.
• Starting 2026-07, the Cart emits PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION and DELIVERY_SELECTED_OPTION_NOT_AVAILABLE warnings so your UI can surface them to buyers.
• Storefront MCP get_cart/update_cart tools are deprecated in favour of UCP Cart MCP, with the old tools maintained only until August 31, 2026.

The versioning model: how Shopify's quarterly release cycle works

Shopify releases a new Storefront API version every three months, January, April, July, and October. Each stable version is guaranteed not to change during its supported lifetime, and each stable version is supported for a minimum of 12 months, meaning there are at least nine months of overlap between two consecutive releases. That overlap is your migration window.

There are three track types to understand:

• Stable (e.g., 2026-04), safe for production, guaranteed backwards compatibility.
• Release candidate (e.g., 2026-07), published on the same day as the new stable release, available now for testing but not recommended for production.
• Unstable, updated continuously, features can disappear without notice; dev/test only.

One gotcha worth knowing: if your integration targets an inaccessible (retired) version, Shopify silently falls forward and serves the oldest accessible stable version. The X-Shopify-API-Version response header will differ from what you requested, that is your signal that you have drifted off a supported version and are at risk of silent breaking changes.

For apps published on the Shopify App Store, the stakes are higher. Apps that continue to use unsupported resources after the upgrade deadline get delisted from the App Store, with users blocked from installing them for a minimum of seven days.

API version comparison: stable, release candidate, and unstable tracks

What actually changed in 2026-04 (the current stable version)

Hydrogen skeleton bumped to 2026-04. If you pinned your Hydrogen config to 2026-01, you need to update. The skeleton package (skeleton@2026.4.0) now targets 2026-04 across Storefront API and Customer Account API calls.

Metaobject access in Shopify Functions. 2026-04 makes it possible for Shopify Functions to query metaobject data directly. If you have Functions-based discount or delivery logic that could benefit from reading metaobject definitions at runtime, this is now available.

JSON metafield cap at 128KB. Starting with API version 2026-04, Shopify caps JSON metafield values at 128KB. If your storefront reads large JSON metafields, audit your data now before any version upgrade breaks payloads silently.

The 2026-07 breaking changes: what headless builds need to patch

Shopify's Summer 2026 Edition (codename Compass) shipped 65 product updates. The Storefront API 2026-07 introduces breaking changes to cart and product query structures that affect every headless build, Hydrogen, Next.js Commerce, Nuxt, or fully custom.

Here is what requires attention before October:

Cart warning signals. Starting with 2026-07, the Cart object emits two new warning types:

• PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION, fires when a cart line contains a product not available in the buyer's location. Each affected cart line returns its own warning, with the target set to the Cart Line ID so you can map it back to the correct line in your UI.
• DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, fires when a buyer's chosen delivery option becomes unavailable (for example, after a cart address change). Previously, the system switched delivery options silently with no notification to the buyer. Now you can detect this programmatically and prompt the buyer to choose again.

Metaobject enum removal. The deprecated PRIVATE and PUBLIC_READ access control enums on metaobject definitions are removed in 2026-07. If your app or storefront references these enum values, update to the current access control model before the release goes stable.

Discount field restructuring. 2026-07 restructures discount-related fields on the Cart. If your storefront has any custom discount display or coupon logic, begin refactoring against the release candidate now. Hydrogen users get codemods for most structural field renames; custom frameworks are on their own, and remediation estimates land between $8,000 and $40,000 depending on storefront complexity.

The October 2026 deadline is firm. API version 2024-10 sunsets in October 2026. Five months sounds comfortable, it is not, once you factor in staging deploys, regression testing, and the fact that cart logic is typically the most fragile part of any headless stack. Start testing against the 2026-07 release candidate now.

Privacy-compliant checkouts with @inContext visitorConsent

This one landed in 2025-10 and remains one of the most practically useful Storefront API additions in recent memory. The @inContext directive now accepts a visitorConsent parameter, allowing developers to pass buyer consent preferences, analytics, preferences, marketing, and sale of data, to cart operations.

The mechanics are clean: you encode consent into the cartCreate or cartBuyerIdentityUpdate mutation like this:

@inContext(visitorConsent: {
  analytics: true,
  preferences: true,
  marketing: false,
  saleOfData: false
})

The consent information is automatically encoded and included in the resulting checkoutUrl, ensuring privacy compliance throughout the checkout process. Shopify reads the _cs parameter it appends to the URL during checkout, do not strip it.

This matters for GDPR and similar regimes. Headless storefronts that previously had no clean way to propagate consent from a cookie banner through to the checkout now have a first-party mechanism built into the API itself. There is no excuse for a modern headless build not to implement this.

Rate limits: the new bot and agent reality

Shopify now applies stricter rate limits to bots and agents that access the Storefront API and Shopify-hosted online store pages. Bots and agents that do not sign their requests are subject to the strictest limits; to qualify for higher rate limits, operators should sign requests using Web Bot Auth.

For legitimate merchants and developers, the practical implication is twofold:

1. If you operate a custom crawler, price aggregator, or AI shopping agent that hits Storefront API endpoints, sign your requests or expect throttling.
2. If you are building a Storefront MCP integration (see the next section), ensure your agent profile is properly registered so it receives the appropriate access tier.

Note that the Storefront API has no rate limit applied to the number of legitimate buyer requests, it is designed to scale through flash sales without you managing concurrency. The new limits specifically target malicious or unidentified bot traffic.

Agentic commerce: Storefront API meets UCP and MCP

This is the most structurally significant shift in the Storefront API's role in 2026. The API is no longer just the backbone for headless human-facing storefronts. It is now the entry point for AI agents.

Shopify co-developed the Universal Commerce Protocol (UCP) with Google as the open standard for how AI agents transact with merchants. UCP covers the full commerce journey from discovery through carts to checkout, and it has broad industry support including Amazon, Meta, Microsoft, Salesforce, Stripe, and Wayfair.

For developers, the concrete implementation surface is the Storefront MCP server. Each Shopify store has its own MCP endpoint exposing storefront features including product search, cart operations, and policy questions. The search_catalog, lookup_catalog, and get_product tools conform to the UCP specification.

Critical migration note: The legacy Storefront MCP cart tools (get_cart and update_cart) are being deprecated in favour of the UCP Cart MCP. The deprecated tools will be maintained until August 31, 2026, that is the same quarter as the 2024-10 API sunset. Two migrations are converging on the same autumn deadline.

If you are building a branded agent or a custom AI shopping experience, the architecture is straightforward:

• Use Storefront MCP for catalog search and product detail retrieval.
• Use UCP Cart MCP for cart operations (add, update, read line items).
• Use Checkout Kit (or the upcoming Checkout MCP, currently in partner preview) for the payment handoff.

For merchants who are not building custom agents, the practical action is simpler: toggle on the AI channels you want to sell through in Shopify admin via Agentic Storefronts, and Shopify handles the protocol work. ChatGPT, Google AI Mode, Perplexity, and Microsoft Copilot are all reachable through a single admin configuration.

Authentication and access tokens: what changes in January 2027

One item that falls outside the 2026 API version cycle but directly affects Storefront API integrations: starting January 1, 2027, all public apps must use expiring offline access tokens for Admin API calls. This is an Admin API change, not a Storefront API change, but many integrations use both together, if your headless build relies on a long-lived Admin API token for backend operations (inventory sync, order management, metafield writes), you need to plan that migration alongside your Storefront API version upgrade.

Your migration checklist for the rest of 2026

Here is the sequenced action list, ordered by urgency:

1. Check your current pinned version. Open your Hydrogen config or GraphQL query headers. Anything older than 2025-07 needs immediate attention.
2. Test against 2026-07 RC. Spin up a staging environment against the release candidate. Focus on cart mutations and any custom discount display logic.
3. Implement visitorConsent on @inContext. If your headless build does not yet propagate cookie consent through to the checkoutUrl, add it now. It requires API version 2025-10 or later.
4. Replace deprecated metaobject enums. Remove any PRIVATE or PUBLIC_READ references before 2026-07 goes stable on July 1.
5. Migrate from Storefront MCP cart tools to UCP Cart MCP. Deadline: August 31, 2026.
6. Audit JSON metafields over 128KB. Required before any 2026-04+ upgrade.
7. Register a Web Bot Auth signature if you operate any bot or agent that hits Storefront API endpoints.

If you need hands-on help planning or executing any of these migrations, the Shopify developer services I offer cover version upgrades, headless architecture reviews, and Storefront API performance audits.