[ci] release 2025.10.0

[shopify-github-actions-access]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@shopify/hydrogen@2025.10.0

Major Changes

• Update Storefront API and Customer Account API to version 2025-10 (#3352) by @fredericoo

Minor Changes

• Add cartDeliveryAddressesReplaceDefault to handle the new cartDeliveryAddressesReplace Storefront API mutation (2025-10) (#3406) by @kdaviduik

  This new mutation replaces all delivery addresses on a cart in a single operation.

  Usage via cart handler:

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

  Usage via CartForm:

  <CartForm action={CartForm.ACTIONS.DeliveryAddressesReplace}>
    {/* form inputs */}
  </CartForm>

• Add cartGiftCardCodesAdd mutation (#3401) by @kdaviduik

  New Feature: cartGiftCardCodesAdd

  Adds gift card codes without replacing existing ones.

  Before (2025-07):

  const codes = ['EXISTING1', 'EXISTING2'];
  await cart.updateGiftCardCodes(['EXISTING1', 'EXISTING2', 'NEW_CODE']);

  After (2025-10):

  await cart.addGiftCardCodes(['NEW_CODE']);

  Verified API Behavior

  Scenario	Behavior
  Valid gift card code	Applied successfully
  UPPERCASE code	Works (API is case-insensitive)
  Duplicate code in same call	Idempotent - applied once, no error
  Re-applying already applied code	Idempotent - no error, no duplicate
  Multiple different codes	All applied successfully
  Invalid code	Silently rejected (no error surfaced)
  Code with whitespace	Rejected (API does not trim whitespace)
  Empty input	Graceful no-op

  Note: The API handles duplicate gift card codes gracefully - submitting an already-applied code results in silent success (idempotent behavior), not an error. No DUPLICATE_GIFT_CARD error code exists.

  Note on whitespace: The API does NOT trim whitespace from codes. Ensure codes are trimmed before submission if accepting user input.

  API Reference

  New method:

  • cart.addGiftCardCodes(codes) - Appends codes to cart
  • CartForm.ACTIONS.GiftCardCodesAdd - Form action

  Skeleton Template Changes

  The skeleton template has been updated to use the new cartGiftCardCodesAdd mutation:

  • Removed UpdateGiftCardForm component from CartSummary.tsx
  • Added AddGiftCardForm component using CartForm.ACTIONS.GiftCardCodesAdd

  If you customized the gift card form in your project, you may want to migrate to the new Add action for simpler code.

  Usage

  import {CartForm} from '@shopify/hydrogen';
  
  <CartForm action={CartForm.ACTIONS.GiftCardCodesAdd} inputs={{giftCardCodes: ['CODE1', 'CODE2']}}>
    <button>Add Gift Cards</button>
  </CartForm>

  Or with createCartHandler:

  const cart = createCartHandler({storefront, getCartId, setCartId});
  await cart.addGiftCardCodes(['SUMMER2025', 'WELCOME10']);

• Add visitorConsent support to @inContext directive for Storefront API parity (#3408) by @kdaviduik

  Note: Most Hydrogen storefronts do NOT need this feature.

  This API addition provides Storefront API 2025-10 parity for the visitorConsent parameter in @inContext directives. However, if you're using Hydrogen's analytics provider or Shopify's Customer Privacy API (including third-party consent services integrated with it), consent is already handled automatically and you don't need to use this.

  This feature is primarily intended for Checkout Kit and other non-Hydrogen integrations that manage consent outside of Shopify's standard consent flow.

  What it does:
  When explicitly provided, visitorConsent encodes buyer consent preferences (analytics, marketing, preferences, saleOfData) into the cart's checkoutUrl via the _cs parameter.

Patch Changes

• cart.updateDeliveryAddresses mutation now clears all delivery addresses when passed an empty array (#3393) by @fredericoo

  Breaking Behavior Change in Storefront API 2025-10

  The cartDeliveryAddressesUpdate mutation now clears all delivery addresses when passed an empty array. This behavior was undefined in previous API versions.

  What Changed

  Before (API ≤ 2025-07):
  Passing an empty array did not update any addresses, essentially a no-op.

  After (API ≥ 2025-10):
  Passing an empty array explicitly clears all delivery addresses from the cart.

  Usage

  context.cart.updateDeliveryAddresses([]);

  Migration

  If you are relying on cart.updateDeliveryAddresses([]) in your codebase, verify if the new behavior is compatible with your expectations.

  Otherwise, no migration is required.

• Updated dependencies [0e61522871fd7500b9cbfa5d15db685deab4c802, cd653456fbd1e7e1ab1f6fecff04c89a74b6cad9, b79b6fc39cdd28e3c73240c4f5e53339feb49561, 38f8a79625838a9cd4520b20c0db2e5d331f7d26]:

  • @shopify/hydrogen-react@2026.0.0

@shopify/hydrogen-react@2025.10.0

Major Changes

• Update Storefront API and Customer Account API to version 2025-10 (#3352) by @fredericoo

Minor Changes

• Add visitorConsent support to @inContext directive for Storefront API parity (#3408) by @kdaviduik

  Note: Most Hydrogen storefronts do NOT need this feature.

  This API addition provides Storefront API 2025-10 parity for the visitorConsent parameter in @inContext directives. However, if you're using Hydrogen's analytics provider or Shopify's Customer Privacy API (including third-party consent services integrated with it), consent is already handled automatically and you don't need to use this.

  This feature is primarily intended for Checkout Kit and other non-Hydrogen integrations that manage consent outside of Shopify's standard consent flow.

  What it does:
  When explicitly provided, visitorConsent encodes buyer consent preferences (analytics, marketing, preferences, saleOfData) into the cart's checkoutUrl via the _cs parameter.

Patch Changes

• Add parent prop to AddToCartButton for nested cart lines (#3398) by @fredericoo

  The AddToCartButton component now accepts an optional parent prop, allowing you to add items as children of an existing cart line. This enables adding warranties, gift wrapping, or other add-ons that should be associated with a parent product.

  Usage

  import {AddToCartButton} from '@shopify/hydrogen-react';
  
  // Add a warranty as a child of an existing cart line (by line ID)
  <AddToCartButton
    variantId="gid://shopify/ProductVariant/warranty-123"
    parent={{parentLineId: 'gid://shopify/CartLine/parent-456'}}
  >
    Add Extended Warranty
  </AddToCartButton>
  
  // Add a warranty as a child of a cart line (by merchandise ID)
  // Useful when you know the product variant but not the cart line ID
  <AddToCartButton
    variantId="gid://shopify/ProductVariant/warranty-123"
    parent={{merchandiseId: 'gid://shopify/ProductVariant/laptop-456'}}
  >
    Add Extended Warranty
  </AddToCartButton>

  Type

  interface AddToCartButtonPropsBase {
    // ... existing props
    /** The parent line item of the item being added to the cart. Used for nested cart lines. */
    parent?: CartLineParentInput;
  }

• Add support for article_reference and list.article_reference metafield types (#3407) by @kdaviduik

  These new metafield types were introduced in Storefront API 2025-10, allowing merchants to reference blog articles in metafields.

@shopify/cli-hydrogen@11.1.8

Patch Changes

• Update Storefront API and Customer Account API to version 2025-10 (#3352) by @fredericoo

• Add support for Bun's text-based lockfile (bun.lock) introduced in Bun 1.2, and npm's shrinkwrap lockfile (npm-shrinkwrap.json), as alternatives to their respective primary lockfiles (bun.lockb and package-lock.json). (#3405) by @thomasKn

• Add cartGiftCardCodesAdd mutation (#3401) by @kdaviduik

  New Feature: cartGiftCardCodesAdd

  Adds gift card codes without replacing existing ones.

  Before (2025-07):

  const codes = ['EXISTING1', 'EXISTING2'];
  await cart.updateGiftCardCodes(['EXISTING1', 'EXISTING2', 'NEW_CODE']);

  After (2025-10):

  await cart.addGiftCardCodes(['NEW_CODE']);

  Verified API Behavior

  Scenario	Behavior
  Valid gift card code	Applied successfully
  UPPERCASE code	Works (API is case-insensitive)
  Duplicate code in same call	Idempotent - applied once, no error
  Re-applying already applied code	Idempotent - no error, no duplicate
  Multiple different codes	All applied successfully
  Invalid code	Silently rejected (no error surfaced)
  Code with whitespace	Rejected (API does not trim whitespace)
  Empty input	Graceful no-op

  Note: The API handles duplicate gift card codes gracefully - submitting an already-applied code results in silent success (idempotent behavior), not an error. No DUPLICATE_GIFT_CARD error code exists.

  Note on whitespace: The API does NOT trim whitespace from codes. Ensure codes are trimmed before submission if accepting user input.

  API Reference

  New method:

  • cart.addGiftCardCodes(codes) - Appends codes to cart
  • CartForm.ACTIONS.GiftCardCodesAdd - Form action

  Skeleton Template Changes

  The skeleton template has been updated to use the new cartGiftCardCodesAdd mutation:

  • Removed UpdateGiftCardForm component from CartSummary.tsx
  • Added AddGiftCardForm component using CartForm.ACTIONS.GiftCardCodesAdd

  If you customized the gift card form in your project, you may want to migrate to the new Add action for simpler code.

  Usage

  import {CartForm} from '@shopify/hydrogen';
  
  <CartForm action={CartForm.ACTIONS.GiftCardCodesAdd} inputs={{giftCardCodes: ['CODE1', 'CODE2']}}>
    <button>Add Gift Cards</button>
  </CartForm>

  Or with createCartHandler:

  const cart = createCartHandler({storefront, getCartId, setCartId});
  await cart.addGiftCardCodes(['SUMMER2025', 'WELCOME10']);

• Add support for nested cart line items (warranties, gift wrapping, etc.) (#3398) by @fredericoo

  Storefront API 2025-10 introduces parentRelationship on cart line items, enabling parent-child relationships for add-ons. This update displays nested line items in the cart.

  Changes

  • Updates GraphQL fragments to include parentRelationship and lineComponents fields
  • Updates CartMain and CartLineItem to render child line items with visual hierarchy

  Note

  This update focuses on displaying nested line items. To add both a product and its child (e.g., warranty) in a single action:

  <AddToCartButton
    lines={[
      {merchandiseId: 'gid://shopify/ProductVariant/laptop-456', quantity: 1},
      {
        merchandiseId: 'gid://shopify/ProductVariant/warranty-123',
        quantity: 1,
        parent: {merchandiseId: 'gid://shopify/ProductVariant/laptop-456'},
      },
    ]}
  >
    Add to Cart with Warranty
  </AddToCartButton>

@shopify/create-hydrogen@5.0.28

Patch Changes

• Add cartGiftCardCodesAdd mutation (#3401) by @kdaviduik

  New Feature: cartGiftCardCodesAdd

  Adds gift card codes without replacing existing ones.

  Before (2025-07):

  const codes = ['EXISTING1', 'EXISTING2'];
  await cart.updateGiftCardCodes(['EXISTING1', 'EXISTING2', 'NEW_CODE']);

  After (2025-10):

  await cart.addGiftCardCodes(['NEW_CODE']);

  Verified API Behavior

  Scenario	Behavior
  Valid gift card code	Applied successfully
  UPPERCASE code	Works (API is case-insensitive)
  Duplicate code in same call	Idempotent - applied once, no error
  Re-applying already applied code	Idempotent - no error, no duplicate
  Multiple different codes	All applied successfully
  Invalid code	Silently rejected (no error surfaced)
  Code with whitespace	Rejected (API does not trim whitespace)
  Empty input	Graceful no-op

  Note: The API handles duplicate gift card codes gracefully - submitting an already-applied code results in silent success (idempotent behavior), not an error. No DUPLICATE_GIFT_CARD error code exists.

  Note on whitespace: The API does NOT trim whitespace from codes. Ensure codes are trimmed before submission if accepting user input.

  API Reference

  New method:

  • cart.addGiftCardCodes(codes) - Appends codes to cart
  • CartForm.ACTIONS.GiftCardCodesAdd - Form action

  Skeleton Template Changes

  The skeleton template has been updated to use the new cartGiftCardCodesAdd mutation:

  • Removed UpdateGiftCardForm component from CartSummary.tsx
  • Added AddGiftCardForm component using CartForm.ACTIONS.GiftCardCodesAdd

  If you customized the gift card form in your project, you may want to migrate to the new Add action for simpler code.

  Usage

  import {CartForm} from '@shopify/hydrogen';
  
  <CartForm action={CartForm.ACTIONS.GiftCardCodesAdd} inputs={{giftCardCodes: ['CODE1', 'CODE2']}}>
    <button>Add Gift Cards</button>
  </CartForm>

  Or with createCartHandler:

  const cart = createCartHandler({storefront, getCartId, setCartId});
  await cart.addGiftCardCodes(['SUMMER2025', 'WELCOME10']);

skeleton@2025.10.0

Major Changes

• Update Storefront API and Customer Account API to version 2025-10 (#3352) by @fredericoo

Patch Changes

• Add support for nested cart line items (warranties, gift wrapping, etc.) (#3398) by @fredericoo

  Storefront API 2025-10 introduces parentRelationship on cart line items, enabling parent-child relationships for add-ons. This update displays nested line items in the cart.

  Changes

  • Updates GraphQL fragments to include parentRelationship and lineComponents fields
  • Updates CartMain and CartLineItem to render child line items with visual hierarchy

  Note

  This update focuses on displaying nested line items. To add both a product and its child (e.g., warranty) in a single action:

  <AddToCartButton
    lines={[
      {merchandiseId: 'gid://shopify/ProductVariant/laptop-456', quantity: 1},
      {
        merchandiseId: 'gid://shopify/ProductVariant/warranty-123',
        quantity: 1,
        parent: {merchandiseId: 'gid://shopify/ProductVariant/laptop-456'},
      },
    ]}
  >
    Add to Cart with Warranty
  </AddToCartButton>

• Updated dependencies [cd653456fbd1e7e1ab1f6fecff04c89a74b6cad9, 24d26ad94e90ab0a859c274838f7f31e75a7808c, 13a6f8987ea20d33a30a9c0329d7c11528b892ea, 403c1f5b6e266c3dfad30f7cfed229e3304570b0, 38f8a79625838a9cd4520b20c0db2e5d331f7d26]:

  • @shopify/hydrogen@2026.0.0

[shopify]

Oxygen deployed a preview of your changeset-release/main branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM
sitemap	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM
classic-remix	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 27, 2026 5:24 PM

Learn more about Hydrogen's GitHub integration.