Shopify Breaking Changes April 2026: What Developers Must Fix Now

Shopify Developer Shakeup: The Full 2026-04 API Wave Hitting This Week

Three significant changes to the Shopify developer platform are shipping in the same week. If you build Shopify apps, maintain Hydrogen storefronts, or manage partner organizations, here is what changed, what's mandatory, and what to do before April 1.

1. RBAC for partner organizations is live (March 30)

Shopify just shipped role-based access control for all partner organizations. This is the biggest change to partner account management in years.

What changed:

• Seven system roles covering organization administration, store access, app development, and collaborator permissions

• Custom roles for anything the system roles don't cover

• New org structure: One Organization Owner + multiple Organization Admins. Previous co-owners have been migrated to Organization Admin, retaining the same access

• Unified Dev Dashboard: Dev stores, client transfer stores, and collaborator stores are now consolidated in one place — no more switching between dashboards

• Automatic migration: Your org has already been migrated. No action required to activate RBAC

What hasn't changed:

Payouts, app distribution, theme submissions, and referrals remain in the Partner Dashboard. RBAC applies to user management and store access only.

What you should do today:

• Open your Partner Dashboard → Dev Dashboard

• Review the roles assigned to each team member after auto-migration

• Verify that no one has Organization Admin access who shouldn't

• Create custom roles for contractors or temporary collaborators with scoped permissions

• Remove any unused accounts that were previously hard to audit

The auto-migration preserves existing access, but it's the perfect opportunity to clean up permissions that accumulated over time. If you have team members who only need access to specific stores, create a custom role instead of leaving them as admins.

Source: Shopify Dev Changelog — RBAC for partners

2. Expiring offline access tokens mandatory tomorrow (April 1)

Starting April 1, 2026, every new public app submitted to the Shopify App Store must use expiring offline access tokens. This is not optional.

Who's affected:

• ✅ New public apps created on or after April 1, 2026 that call the Admin API

• ❌ NOT affected: Public apps created before April 1 (grandfathered)

• ❌ NOT affected: Custom apps created at any time

• ❌ NOT affected: Apps created by merchants in Dev Dashboard or admin

Why Shopify is doing this:

Non-expiring tokens are a security liability. If a token leaks — through a compromised CI/CD pipeline, a misconfigured log, or a breached third-party service — it provides permanent access to merchant data. Expiring tokens limit the blast radius. A leaked token is useless after it expires, and the refresh flow gives Shopify an additional verification checkpoint.

This aligns with modern OAuth practices. Most major platforms (Google, Microsoft, GitHub) moved to expiring tokens years ago. Shopify is catching up.

What your auth flow needs:

Your app must handle the token refresh cycle:

• Initial install: Receive an access token with a limited lifespan

• Before expiry: Use the refresh token to obtain a new access token

• Store securely: Both the access token and refresh token must be stored server-side

If you're using Shopify's official app templates and libraries (@shopify/shopify-app-remix, @shopify/shopify-app-express), token refresh is already handled. Check that you're on the latest version.

If you're building custom auth:

• Implement a token refresh middleware that checks expiry before each Admin API call

• Add error handling for expired-token responses (HTTP 401)

• Store refresh tokens encrypted at rest

• Test the full refresh cycle in a dev store before submitting to the App Store

CI/CD considerations:

If your deployment pipeline uses offline access tokens for automated tasks (data migration, bulk operations, scheduled syncs), verify that your pipeline can handle token refresh. Hardcoded tokens in environment variables won't work for new apps.

Sources:

• Shopify Dev Changelog — Expiring tokens

• Shopify Community — Expiring tokens discussion

• Shopify Docs — Expiring vs. non-expiring offline tokens

3. Shopify CLI --force flag deprecated (removal in May 2026)

Shopify is removing the --force flag from shopify app deploy and shopify app release. If your CI/CD pipeline uses --force, it will break in May.

Why:

The --force flag skips ALL confirmation prompts — including prompts for extension deletions that permanently remove data on installed shops. It doesn't distinguish between safe operations (adding/updating extensions) and destructive ones (deleting extensions with merchant data).

The replacement:

Two granular flags that separate safe from destructive operations:

# Safe: allows adding and updating extensions, blocks deletions
shopify app deploy --config production --allow-updates

# Destructive: explicitly permits extension deletion (use with caution)
shopify app deploy --config production --allow-updates --allow-deletes

What to do now:

• Search your CI/CD configs for --force:

grep -r "\-\-force" .github/workflows/ .gitlab-ci.yml Jenkinsfile Makefile

• Replace --force with --allow-updates in all automated deployment scripts

• Only add --allow-deletes in manual workflow runs where you explicitly intend to remove extensions

• Test the updated pipeline in a development environment before the May removal

Timeline:

• March 25, 2026: Deprecation announced, --force still works but generates warnings

• May 2026: --force removed entirely — pipelines using it will fail

Don't wait until May. Update your scripts this week while you're already auditing your Shopify developer setup.

Source: Shopify Dev Changelog — CLI --force deprecation

Updated April 2: The rest of the 2026-04 API wave developers should not ignore

When this post first went live, the focus was on the most immediate developer shakeups landing between March 31 and April 1.

Since then, the full Shopify API 2026-04 release has come into focus — and there are several additions Hydrogen teams should move on immediately.

This is the part of the update that matters most if you're building custom discount logic, checkout extensions, or multi-market storefronts.

4. Checkout metafields are deprecated — migrate before your next extension release

This is the biggest breaking change in the 2026-04 wave.

If you're using checkout metafields in checkout UI extensions, Shopify's migration path is now explicit:

• Use cart metafields for checkout UI extensions

• Use order metafields for customer account UI extensions

If your team leaves this until the next unrelated deployment, it becomes exactly the kind of "small platform change" that turns into rushed production work later.

A practical migration checklist:

• Audit all checkout and customer account extensions using checkout metafields

• Map each data point to either cart metafields or order metafields

• Update read/write logic in your extensions

• Test downstream flows that depend on those values

• Ship the migration before the next major release window

For Hydrogen teams, this is not optional cleanup. It belongs in the active sprint queue.

Source: Shopify Dev Changelog — Checkout metafields deprecation

5. Metaobject access inside Shopify Functions is a major unlock

This is the most interesting opportunity-side change in the 2026-04 release.

Shopify Functions can now query metaobject entries by handle or ID in input queries.

That opens much cleaner implementation patterns for things like:

• tiered pricing rules

• configurable bundle logic

• merchant-managed promotional conditions

• reusable business rule objects shared across campaigns

For a Hydrogen storefront, that means more commerce logic can move out of hardcoded conditionals and into structured merchant-managed data.

A practical use case:

• A merchandiser manages bundle definitions in metaobjects

• A Function reads the relevant configuration directly

• The storefront and discount layer stay aligned without duplicating rules in code

That is a much better model than redeploying every time a campaign changes.

Source: Shopify Dev Changelog — Metaobject access in Functions

6. BXGY discount prerequisites reduce custom logic debt

2026-04 also adds prerequisites to product discount functions for buy-X-get-Y promotions.

That sounds small until you look at how many teams were previously stitching these conditions together with custom workarounds.

For developers, the win is straightforward:

• less custom logic to maintain

• more native support for common campaign structures

• cleaner promotional implementation in Shopify Functions

If your team runs bundle campaigns or threshold-based promotional logic, this is worth revisiting now rather than carrying workaround logic forward into Q2.

Source: Shopify Dev Changelog — BXGY prerequisites

7. Metafield translations via GraphQL Admin API help international Hydrogen builds

For multi-market storefronts, translated metafields are now queryable via the GraphQL Admin API.

This removes one of the more annoying content architecture workarounds in international Shopify builds.

Why it matters:

• localized metafield values are easier to manage

• custom translation layers can get simpler

• Hydrogen teams can build cleaner market-aware content models

This won't be the headline feature for most teams, but it will save real implementation friction for stores operating across languages and regions.

Source: Shopify Dev Changelog — Metafield translations

8. Multi-channel sales app support matters for structured commerce workflows

Shopify also added multi-channel support for sales channel apps, allowing apps to manage multiple connections with distinct specs.

Not every Hydrogen team will touch this directly.

But it continues the broader pattern of Shopify investing in structured, API-first commerce infrastructure — the same direction that benefits modern headless teams most.

Source: Shopify Dev Changelog — Multi-channel support

Updated April 16: skeleton@2026.4.0 shipped — plus 2026-07 preview changes

The original wave was March 31 to April 1. The April 2 update covered the broader 2026-04 API release.

Now, two weeks later, there is another batch of changes that Hydrogen teams need to act on — including a major skeleton release, a 2026-07 preview with discount field restructuring, a hard deprecation deadline for Shopify Scripts, and new developer tooling.

9. Hydrogen skeleton@2026.4.0: the breaking changes that matter

skeleton@2026.4.0 shipped April 9 and it is a significant bump. Here is what Hydrogen teams need to address.

Storefront API and Customer Account API bumped from 2026-01 → 2026-04.

This is the headline change. If you pinned your API version to 2026-01 in your Hydrogen config or GraphQL queries, the skeleton template now defaults to 2026-04. That means you get access to the latest fields and deprecations take effect.

JSON metafield writes now capped at 128KB.

This is the breaking change most likely to cause production issues.

When using API version 2026-04 or later, the Storefront API limits JSON type metafield writes to 128KB. Apps that used JSON metafields before April 1, 2026 are grandfathered at the existing 2MB limit. Everyone else gets the new cap. Large metafield values continue to be readable by all API versions.

If you store rich product content, configuration data, or structured attributes in JSON metafields, audit your catalog now. Anything over 128KB will fail silently on write.

New cart error code: MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR.

Cart operations (cartCreate, cartLinesAdd, etc.) now return a specific error code when a Cart Transform Function fails at runtime — instead of the previous generic INVALID error code.

If your storefront handles cart errors in its UI, add handling for this new code. The generic catch-all no longer covers Transform Function failures.

Redundant Storefront API proxy route removed.

The skeleton template previously included a manual Storefront API proxy route. This is now handled by proxyStandardRoutes: true (which is the default in Hydrogen 2026.1.4+). If you were using the manual proxy, switch to the built-in one.

Source: skeleton@2026.4.0 release notes

10. 2026-07 Preview: Storefront API discount fields overhaul

This is the biggest change coming in the next API version, and the preview is already live. If your Hydrogen storefront has any custom discount logic, start updating now.

What's deprecated:

• cart.discountAllocations — the top-level field is gone. Use cart.lines[].discountAllocations(lineLevelOnly: false) for product discounts and cart.deliveryGroups[].discountAllocations for shipping discounts.

• cartDiscountAllocation.discountApplication — replaced by sourceDiscountApplication. The old field had a long-standing bug where value returned the per-line allocated amount instead of the configured discount amount. A $10 fixed discount allocated as $4 to one line showed value: $4. The new field returns the correct configured amount.

What's new:

• cart.discountApplications — lists all discounts (product, shipping, and order) currently applied to the cart.

• cartDiscountAllocation.sourceDiscountApplication — returns the discount application with the correct configured value and concrete type information. Use GraphQL fragments for type-specific fields: sourceDiscountApplication { ... on CartCodeDiscountApplication { code } }.

• baseCartDiscountApplication.totalAllocatedAmount — shows the total discount amount allocated across the entire cart. A 10% discount that splits as $4 on line A and $6 on line B will show totalAllocatedAmount: $10 on both lines.

• cart.deliveryGroups[].discountAllocations — displays discounts allocated to delivery groups.

• cart.lines[].discountAllocations(lineLevelOnly: Boolean) — the new argument lets you request either only product-level discounts or all discounts allocated to the line. Defaults to true for backward compatibility.

Action items:

• Update all cart discount queries to use sourceDiscountApplication instead of discountApplication
• Replace cart.discountAllocations with line-level and delivery group queries
• Test with percentage, fixed amount, and free shipping discounts
• Start before 2026-07 goes stable — this is not a small refactor

Source: Storefront API 2026-07 discount changes

11. Shopify Scripts die June 30 — 75 days left

This is no longer a future concern. It is an active deadline.

Shopify Scripts will stop executing entirely on June 30, 2026. Editing and publishing new Scripts was already disabled on April 15, 2026.

If your store is still running Shopify Scripts for discounts, shipping, or payment customization, migration to Shopify Functions is mandatory. The Shopify Scripts customizations report will help you identify what needs to move.

Shopify Functions now cover:

• ✅ Discounts
• ✅ Shipping
• ✅ Payments

The migration path is well-documented. The timeline is not flexible. If your team hasn't started, start now.

Source: Shopify Dev Changelog — Scripts deprecation

12. New developer tools: UI extension testing and more

Two new additions that matter for Hydrogen and app development teams.

@shopify/ui-extensions-tester — AI-agent-friendly unit testing for extensions

Shopify shipped an official testing library for UI extensions in API version 2026-04. @shopify/ui-extensions-tester lets you write unit tests for extensions on any surface — Checkout, Admin, Customer Accounts, and POS — without a running Shopify host.

Key capabilities:

• Render extensions in a standard DOM environment and query output
• Type-safe mocks using the same types as the real extension API
• Surface-specific defaults for each target surface
• Event simulation for user interactions and async state changes
• Shopify explicitly describes it as "AI-agent friendly" — the strongly typed mocks and predictable test patterns work well with AI-assisted test-driven development

If your team uses AI coding tools for extension work, this is the testing library to adopt.

Source: @shopify/ui-extensions-tester docs

LineItem.weight field in Admin API (2026-07)

The LineItem.weight field is now available in the public GraphQL Admin API starting in version 2026-07. It returns a Weight object with value and unit, making it easy to access line item weights without converting from the REST API's grams field. Useful for shipping calculations, fulfillment logic, and product weight display.

Source: Shopify Dev Changelog — LineItem.weight

Metaobject enum cleanup (2026-07)

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

Source: Shopify Dev Changelog — Metaobject enum removal

Bonus: Vercel Fluid Compute eliminates cold starts for Hydrogen

While Shopify shipped security and access control changes, Vercel made a significant infrastructure announcement at Shoptalk 2026 that directly impacts Hydrogen developers.

The problem Fluid Compute solves:

Serverless functions on Hydrogen storefronts have always suffered from cold starts — the delay when a function spins up for the first time after being idle. For standard page loads, cold starts add 200-500ms. For AI-powered features (product recommendations, conversational search, dynamic pricing), the penalty was even worse — often making AI features impractical in production commerce.

What Vercel demoed at Shoptalk:

• AI product recommendations at sub-30ms latency — faster than most non-AI page renders

• Zero cold starts for serverless functions on Hydrogen storefronts

• Real-time dynamic pricing driven by Shopify inventory webhooks, updating storefront prices without full page reloads

• Conversational search using the Vercel AI SDK, running at edge speed

Why this matters for Hydrogen developers:

The "AI features are too slow for commerce" objection is dead. With Fluid Compute:

• AI-powered product recommendations no longer degrade page performance

• Conversational search (powered by Storefront MCP + AI SDK) can run in production without latency concerns

• Dynamic pricing from real-time inventory signals becomes feasible at scale

• The total cost of AI features drops — no more over-provisioning to avoid cold starts

What this means for the Hydrogen vs. Liquid decision:

This widens the performance gap between Hydrogen and Liquid storefronts. Liquid themes on Shopify's CDN deliver consistent but fixed performance. Hydrogen on Vercel/Oxygen now delivers better baseline performance AND can layer AI features on top without degradation.

For merchants evaluating Hydrogen migration, the ROI calculation for AI features just got significantly more favorable.

Source: DigitalApplied — Vercel at Shoptalk 2026: AI Commerce and Fluid Compute

Updated April 18: Week of Apr 13–17 — more breaking changes, Hydrogen patches, and cert renewals

The changes keep coming. The week of April 13–17 brought additional Admin API updates, a Hydrogen patch fixing a cart bug, a payments app certificate renewal deadline, and new tooling for mobile apps.

13. Inventory API now tracks active and inactive levels

Two related changes landed in the Admin GraphQL API (2026-04) that affect how inventory data flows through your app:

isActive field on InventoryLevel — The InventoryLevel object now includes an isActive boolean field indicating whether an inventory level is currently active. Previously, deactivating an inventory level would clear its associated quantities, and inactive levels were invisible through the API. Starting with 2026-04, deactivating no longer clears quantities — and inactive levels are now returned in queries.

includeInactive argument — You can now pass includeInactive: true when querying inventoryLevels or inventoryLevel fields on InventoryItem and Location to explicitly include inactive levels. By default, only active levels are returned.

Impact: If your app queries inventory data, you may see inactive levels that were previously excluded. Add isActive filtering to avoid processing deactivated inventory.

Sources: isActive field, includeInactive argument

14. DraftOrderLineItem.grams removed in 2026-07

The grams field on DraftOrderLineItem is being removed in API version 2026-07. This field was deprecated over 8 years ago.

Migration: Replace any usage of grams with the weight field, which returns both value and unit. This is consistent with the new LineItem.weight field in the public Admin API.

# Before (deprecated)
lineItems(first: 5) {
  nodes { grams }
}

# After
lineItems(first: 5) {
  nodes { weight { value unit } }
}

Source: Shopify Dev Changelog — DraftOrderLineItem.grams removal

15. mTLS certificate renewal for Payments Apps — June 15 deadline

Shopify is renewing its mTLS client certificate used by Payments Apps. The current certificate expires July 24, 2026. The renewal takes effect June 15, 2026.

Who needs to act: Only Payments Apps using custom certificate validation (checking Common Name or other certificate-specific fields). If you use standard mTLS validation, the new cert is signed by the same CA — no action required.

If you're in the custom validation camp, update your logic before June 15.

Source: Shopify Dev Changelog — mTLS certificate renewal

16. New CSS variable for mobile safe area insets

A new CSS custom property, --shopify-safe-area-inset-bottom, is now available for embedded apps running on Shopify Mobile. It provides the exact pixel value of host UI overlays like the floating bottom navigation bar.

The variable is automatically set by App Bridge and defaults to 0px when no overlay is present. If your app has fixed-bottom elements (sticky footers, floating action buttons), use it:

.my-floating-button {
  bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
}

This took effect April 15 for all affected apps.

Source: Shopify Dev Changelog — Mobile safe area CSS variable

17. Hydrogen April 2026 release: what changed since our last update

The Hydrogen April 2026 release (v2026.4.0 + 2026.4.1 patch) shipped several changes beyond the skeleton update and API bump covered earlier.

Storefront API proxy is now mandatory. The proxyStandardRoutes option has been removed from createRequestHandler. The proxy is always on. If your load context does not include a storefront instance, the request handler will throw an error. This is not optional — update your configuration.

Backend consent mode replaces _tracking_consent cookie. The legacy JavaScript-based _tracking_consent cookie is replaced with server-set cookies via the Storefront API proxy. This is the breaking change that triggered the VisitorConsent bug in 2026.4.0 (fixed in 2026.4.1).

@shopify/remix-oxygen is deprecated. Use @shopify/hydrogen/oxygen for createRequestHandler instead. The old import path will stop working in a future release.

10 new Cookbook recipes added. The Hydrogen docs now include recipes for B2B storefronts, metaobjects, infinite scroll, Google Tag Manager, Express checkout, Partytown (for third-party scripts), and more. If you're building on Hydrogen, check the Cookbooks hub before writing custom implementations.

Cart consent bug fix (2026.4.1 patch). @shopify/hydrogen@2026.4.1 and @shopify/hydrogen-react@2026.4.1 fixed cart operations failing on stores without the VisitorConsent type. The visitorConsent parameter is now only included in GraphQL operations when explicitly provided.

If your Hydrogen storefront is on 2026.4.0 and you're seeing cart operation failures after the consent mode migration, update to 2026.4.1.

Sources: Hydrogen April 2026 release, Hydrogen updates hub

Developer checklist: what to do now

Here's the consolidated action list, ordered by urgency.

Immediate (this week)

• Audit JSON metafields — If you store rich content in JSON metafields, check which values exceed 128KB. Apps grandfathered before April 1 are safe. Everything else needs to fit the new limit.

• Add cart error handling — If your storefront handles cart errors, add a case for MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR.

• Check Shopify Scripts status — If you're still running Scripts, migration to Functions is mandatory. June 30 is the hard deadline. April 15 already blocked new Script edits.

• Start discount query migration — The 2026-07 discount field changes are significant. If your storefront has custom discount logic, begin refactoring now before the stable release.

This sprint

• Migrate checkout metafields — Use cart metafields for checkout UI extensions and order metafields for customer account extensions.

• Review metaobject access in Functions — If you have Shopify Functions that could benefit from querying metaobject data, the 2026-04 release makes this possible.

• Set up @shopify/ui-extensions-tester — If you build UI extensions, adopt the new testing library. The AI-agent-friendly patterns pair well with modern coding workflows.

• Update CI/CD scripts — Replace --force with --allow-updates before the May removal.

This month

• Plan 2026-07 API upgrade — The discount field changes and new LineItem.weight field in the Admin API require query updates. Start testing against the preview version.

• Evaluate Fluid Compute — If you're running Hydrogen on Vercel, test Fluid Compute for AI features on your roadmap.

• Review Storefront MCP — If you haven't activated Storefront MCP on your Hydrogen store, the combination with Fluid Compute makes AI agent integration practical.

• Audit partner org roles — Review auto-migrated RBAC roles in your Dev Dashboard.

The bigger picture

April 2026 is the densest month of Shopify developer platform changes in recent memory.

Security is tightening. RBAC and expiring tokens both reduce the surface area for credential-based attacks. The --force flag removal prioritizes safety over convenience in automated workflows.

The API surface is expanding fast. skeleton@2026.4.0 bumped to 2026-04, the 2026-07 preview is already shipping breaking changes, and the discount field restructuring is the most significant Storefront API change in months.

Legacy infrastructure is dying. Shopify Scripts stop executing in 75 days. Checkout metafields are deprecated. Old enum values are being removed. The message is clear: migrate now or deal with forced migrations later.

Developer tooling is maturing. The new UI extension testing library, Storefront MCP, and Fluid Compute all point to a platform that expects AI-assisted development as the default workflow — not an exception.

Building on Hydrogen? Weaverse gives your team visual editing for Hydrogen storefronts — pre-configured for the latest Storefront API version, MCP-ready, and AI-optimized. If you're upgrading to 2026-04 APIs, start with a production-ready foundation that already handles the migration. Try Weaverse free →

Related reading

• Shopify Hydrogen in 2026: The Complete Developer Guide

• Shopify's Agentic Plan: How Non-Shopify Merchants Can Sell in ChatGPT

• Storefront MCP: How to Make Your Hydrogen Store AI-Agent-Ready

• Shoptalk 2026: Agentic Commerce Is Here

• Shopify AI Toolkit: Dev MCP, Cursor, and Claude Code

• Shopify Winter 26: Complete Implementation Guide to Storefront MCP

• Shopify Hydrogen AI Visibility: Fix Your Product Data for ChatGPT Shopping

Sources

• Shopify Dev Changelog — RBAC for partners
• Shopify Dev Changelog — Expiring offline tokens
• Shopify Dev Changelog — CLI --force deprecation
• Shopify Dev Changelog — Checkout metafields deprecation
• Shopify Dev Changelog — Metaobject access in Functions
• Shopify Dev Changelog — BXGY prerequisites
• Shopify Dev Changelog — Metafield translations
• Shopify Dev Changelog — Multi-channel support
• Shopify Dev Changelog — Discount tags
• skeleton@2026.4.0 release notes
• Shopify Dev Changelog — Storefront API 2026-07 discount changes
• Shopify Dev Changelog — Scripts deprecation June 30
• Shopify Dev Changelog — @shopify/ui-extensions-tester
• Shopify Dev Changelog — LineItem.weight
• Shopify Dev Changelog — Metaobject enum removal
• Shopify Community — Expiring tokens thread
• Shopify Dev Changelog — InventoryLevel isActive field
• Shopify Dev Changelog — includeInactive argument
• Shopify Dev Changelog — DraftOrderLineItem.grams removal
• Shopify Dev Changelog — mTLS certificate renewal
• Shopify Dev Changelog — Mobile safe area CSS variable
• Shopify Dev Changelog — Hydrogen April 2026 release
• @shopify/hydrogen@2026.4.1
• @shopify/hydrogen-react@2026.4.1
• Hydrogen Updates Hub
• DigitalApplied — Vercel at Shoptalk 2026