Hydrogen / Releasev2026.4.0

Hydrogen April 2026 release
API updated to 2026-04 + two breaking changes

Storefront API and Customer Account API are updated to 2026-04. Two breaking changes also land: 'API proxy is now always enabled' and 'backend consent mode defaults to ON'. Review the impact before upgrading.

On this page
  1. 30-second overview (key points of this release)
  2. Release overview: what changed
  3. Breaking change ①: Storefront API proxy is now always enabled
  4. Breaking change ②: Backend consent mode defaults to ON
  5. API version update (2026-04)
  6. Upgrade checkpoints
  7. 5 key points for developers
  8. 3 use cases you can apply to your work
  9. One-line summary for proposals

130-second overview

Hydrogen's v2026.4.0 has been released. Storefront API and Customer Account API are updated to 2026-04 , and
additionally two breaking changes around 'API proxy handling' and 'consent handling'have landed. Existing stores may hit errors if upgraded without changes.
2026-04

API to 2026-04

Both Storefront API and Customer Account API are updated to the 2026-04 version. (#3651)

Proxy always enabled

proxyStandardRoutes The option is removed. Throws if storefront is missing from load context. (#3649)

Consent moves server-side

Backend consent mode defaults to ON. The JS _tracking_consent cookie is replaced with a server-set cookie. (#3649)

2Release overview: what changed

Hydrogen v2026.4.0 Upgrade via npm ① Update API to 2026-04 Storefront / Customer Account ② API proxy always enabled proxyStandardRoutes removed ③ Consent mode defaults to ON Cookie set server-side What to do when upgrading Always pass a storefront instance into load context Remove the relevant option from createRequestHandler Re-check consent handling on the assumption of server cookies
Both breaking changes are PRs #3649, and the API version update is a PR #3651.The always-on proxy in ② is a prerequisite for the consent mode in ③(because the consent cookie is set server-side via the Storefront API proxy).

3Breaking change ①: Storefront API proxy is always enabled

The Storefront API proxy, which used to be optionally toggleable, is nowalways enabled. The configuration option is gone, and the prerequisites are stricter.

Previously

the proxy was toggleable

createRequestHandler 's proxyStandardRoutes option controlled whether the standard routes were proxied.

v2026.4.0 onward

Always enabled / option removed

The proxy isalways enabled.proxyStandardRoutes has been createRequestHandler fromremoved. If left in place, fixes are required.

Request createRequestHandler Check the load context storefront present? storefront present Handled normally via the proxy no storefront request handler throws
If the load context does not include a storefront instance, the request handler will throw an error.If you assemble the load context in a custom server entry, be sure to include storefront.

4Breaking change ②: backend consent mode is ON by default

Tracking consent handling has moved from a client-side JS cookie to aserver-set cookie. This is now the default.

Previously: client-side JS cookie Browser JS runs _tracking_consent JS cookie (legacy) v2026.4.0: server-set cookie Storefront API Proxy server-set cookie Server sets it Replace Consent cookies are set server-side via the Storefront API proxy (breaking change ①)
Deprecated

Legacy JS cookie

_tracking_consent the cookie that was set via JavaScript is being replaced.

Now the default

Server-set cookie

Via the Storefront API proxy,the server sets the cookie. This is enabled by default.

5API version update (2026-04)

Both the Storefront API and the Customer Account API have been 2026-04 updated. (#3651)

ScopeNew versionWhat to check
Storefront API 2026-04 Verify that other changes in the 2026-04 changelog don't affect your storefront
Customer Account API 2026-04 Review the other changes listed in the 2026-04 changelog
This article does not cover the individual API changes in 2026-04. Shopify recommends reviewing the "Storefront API 2026-04 changelog" and "Customer Account API 2026-04 changelog" separately. Refer to each changelog for details.

6Upgrade checkpoints (3 steps)

1

Check createRequestHandler

proxyStandardRoutes if you were passing one, remove it (the option has been deprecated).

2

Inspect the load context

make sure the storefront instance is always included. Without it, the request handler will throw.

3

Re-verify the consent flow

Assume server-set cookies._tracking_consent Check for any custom implementations that depend on it.

Finally the Storefront API 2026-04 / Customer Account API 2026-04 changelogs review them and confirm there are no storefront-specific impacts. See the full release notes and GitHub Discussions for details.

75 key points for engineers

!

1. The proxy is always-on by design

proxyStandardRoutes is createRequestHandler has been removed. It can no longer be toggled and is always assumed to be enabled. (#3649)

throw

2. storefront is required in load context

If the load context lacks a storefront instance, the request handler throws. Custom server entries need review.

3. Consent defaults to server-side cookies

The backend consent mode is ON by default._tracking_consent Replace JS cookies with server-set cookies.

4. Items ② and ③ are linked

Consent cookies are set via the Storefront API proxy. Always-on proxy is a prerequisite for consent mode.

2026-04

5. APIs move to 2026-04. Individual changes are not covered in this article

Both Storefront API and Customer Account API are updated to 2026-04 (#3651).Individual API changes introduced in 2026-04 are not covered in this article. You will need to review each API's 2026-04 changelog separately.

8Three use cases you can apply in practice

v2026.4.0
USE CASE 1

Safe upgrade path for existing Hydrogen stores

Challenge
You want to upgrade to v2026.4.0, butproxyStandardRoutes if you are still using it, or if storefront is missing from load context anywhere, you risk errors the moment you upgrade.
Action
createRequestHandler Audit all call sites, remove deprecated options, and make sure a storefront instance is always present in load context before upgrading.
Outcome
Avoid unexpected throws after production deploy and follow the latest version on a planned schedule.
Technical notes
The request handler is designed to throw when storefront is missing (#3649). Verify request handler boot in staging first.
USE CASE 2

Unifying tracking consent on the server side

Challenge
Until now, _tracking_consent consent management relied on JS cookies. Because it assumed client-side JS, it was hard to handle for SSR and for keeping consent state consistent.
Action
Move to the backend consent mode in v2026.4.0 (default ON) and shift to server-set cookies via the Storefront API proxy.
Outcome
Consent state is managed centrally on the server, giving consistent handling that does not depend on JS behavior.
Technical notes
Consent cookies are set by the server through the proxy. Always-on proxy (breaking change ①) is a prerequisite, so validate both together.
Store A Store B Store C Store D
USE CASE 3

Bulk API version updates across multiple Hydrogen stores (managed maintenance)

Challenge
When maintaining multiple Hydrogen stores, Storefront API / Customer Account API versions tend to be left outdated.
Action
Update to v2026.4.0 and align both APIs to 2026-04 . Check the 2026-04 changelog for each store and identify the impact.
Outcome
Eliminate API version fragmentation, reduce future deprecation risk, and standardize maintenance.
Technical notes
Individual 2026-04 API changes are not covered in this post. Be sure to check the 2026-04 changelogs for the Storefront API and Customer Account API separately (#3651).

9One-line summary you can use in proposals

"Hydrogen v2026.4.0 is a major release that updates the APIs to 2026-04.
The API proxy is always enabled (storefront is required in load context), and the default consent mode is a server-configured cookieThese two breaking changes mean that
existing stores should createRequestHandler review their consent flow before upgrading."