Updates

The April release includes two breaking changes to how Hydrogen handles the Storefront API proxy and consent tracking. We've also updated the Storefront API and Customer Account API to 2026-04.

Mandatory Storefront API proxy

The Storefront API proxy is now always enabled. The proxyStandardRoutes option has been removed from createRequestHandler.

Previously, proxyStandardRoutes defaulted to true but could be disabled, and a missing storefront instance in your load context would log a warning:

Code Example
Copy
// Before (v2026.1)
createRequestHandler({
  build,
  getLoadContext,
  proxyStandardRoutes: true, // optional, defaulted to true
});
// Missing storefront in context → console warning, proxy skipped

Now the proxy is always on, and if your load context doesn't include a storefront instance, the request handler throws:

Code Example
Copy
// After (v2026.4)
createRequestHandler({
  build,
  getLoadContext,
  // proxyStandardRoutes is gone — proxy is always enabled
});
// Missing storefront in context → throws Error

If you're using createHydrogenContext() to build your load context, no changes needed. It already provides the storefront instance. If you have a custom getLoadContext that doesn't always return a storefront, you'll need to update it.

Backend consent mode

Hydrogen now sets window.Shopify.customerPrivacy.backendConsentEnabled to true before the Customer Privacy API script loads. This tells the consent library to use server-set cookies via the Storefront API proxy instead of the legacy _tracking_consent JavaScript cookie.

The flag is installed through a property interceptor on window.Shopify that survives the CDN's window.Shopify = {} reset cycle, so it's readable before the full Customer Privacy API is assigned.

If you're using Hydrogen's ShopifyCustomerPrivacy component (or the analytics provider that wraps it), this is automatic. There's no new config to set. The old _tracking_consent cookie path is being deprecated in favor of this server-side approach.

Other changes

For the full list of API-level changes, including a 128KB limit on JSON metafield writes and a new MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR cart error code, see the Storefront API 2026-04 changelog and Customer Account API 2026-04 changelog. The full release notes also cover a fix to React Router peer dependency ranges.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

The Hydrogen January 2026 release (v2026.1.0) updates the Storefront API and Customer Account API to 2026-01. This is a quarterly API version bump with no Hydrogen-specific feature changes.

Review the Storefront API 2026-01 changelog and Customer Account API 2026-01 changelog for details on what changed at the API level, including a now-required discountCodes argument on the cartDiscountCodesUpdate mutation. See the full release notes on GitHub for the complete list.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.

Welcome to the October release! This one adds new cart mutations that cut down on the client-side state juggling required for gift cards and delivery addresses. We've also updated the Storefront API and Customer Account API to 2025-10.

Add gift card codes without re-submitting existing ones

Previously, applying a new gift card code meant reading the codes already on the cart and passing the full list back through cart.updateGiftCardCodes. With cart.addGiftCardCodes, you can append codes directly:

Code Example
Copy
const result = await cart.addGiftCardCodes(['SUMMER2025']);

The skeleton template has been updated to use this new mutation. If you forked the skeleton, here's the pattern. A CartForm posts a single giftCardCode field, and the route action wraps it into an array:

Code Example
Copy
// app/components/CartSummary.tsx
function AddGiftCardForm({children}: {children: React.ReactNode}) {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.GiftCardCodesAdd}
    >
      {children}
    </CartForm>
  );
}

// app/routes/cart.tsx
case CartForm.ACTIONS.GiftCardCodesAdd: {
  const formGiftCardCode = inputs.giftCardCode;
  const giftCardCodes = (
    formGiftCardCode ? [formGiftCardCode] : []
  ) as string[];

  result = await cart.addGiftCardCodes(giftCardCodes);
  break;
}

Replace all delivery addresses in one call

cart.replaceDeliveryAddresses swaps every delivery address on a cart in a single mutation, replacing the old pattern of deleting existing addresses and re-adding new ones:

Code Example
Copy
const result = await cart.replaceDeliveryAddresses([
  {
    address: {
      deliveryAddress: {
        address1: '123 Main St',
        city: 'Anytown',
        countryCode: 'US',
      },
    },
    selected: true,
  },
]);

Also available as CartForm.ACTIONS.DeliveryAddressesReplace.

Other changes

The @inContext directive now accepts an optional visitorConsent parameter for encoding buyer consent preferences into the cart's checkoutUrl. This is intended for Checkout Kit and other non-Hydrogen integrations that manage consent outside Shopify's standard flow. If you're using Hydrogen's analytics provider, you don't need it.

For the full list of API-level changes in Storefront API 2025-10, see the Storefront API changelog and Customer Account API changelog. The full release notes on GitHub cover everything in this release.

To take advantage of all the latest features and improvements in Hydrogen, run npx shopify hydrogen upgrade.