[2025-10] Update Storefront and Customer Account APIs to 2025-10

[juanpprieto]

WHY are these changes introduced?

Fixes #3281

Updates Storefront API and Customer Account API from version 2025-07 to 2025-10 to support the latest quarterly API release. This update enables new features including nested cart lines, gift card addition, delivery address operations, and privacy-compliant checkout flows.

WHAT is this pull request doing?

Version Updates

• API versions: 2025-07 → 2025-10 (SFAPI & CAAPI)
• Package versions: 2025.7.0 → 2025.10.0

Changes Made

Version Constants (3 files)

• packages/hydrogen-react/src/storefront-api-constants.ts - SFAPI_VERSION
• packages/hydrogen/src/customer/constants.ts - DEFAULT_CUSTOMER_API_VERSION
• packages/hydrogen-react/codegen.ts - SF_API_VERSION and CA_API_VERSION

Package Version References (4 files)

• packages/hydrogen/src/version.ts - LIB_VERSION
• packages/hydrogen/src/react-router-preset.ts - preset name and error messages
• packages/hydrogen/src/react-router-preset.test.ts - test expectations
• packages/hydrogen/src/exports.test.ts - test expectations

Generated Types and Schemas (4 files)

• Regenerated GraphQL types from 2025-10 schemas
• storefront-api-types.d.ts - Added 113 new lines (nested cart lines, gift card operations)
• customer-account-api-types.d.ts - Updated with new fields
• Schema JSON files updated

Documentation and Examples (38 files)

• Updated all hardcoded API version references in docs, examples, tests, and stories
• Rebuilt documentation with new API version
• Regenerated skeleton template types

Changeset
Version bumps:

• @shopify/hydrogen: major
• @shopify/hydrogen-react: major
• @shopify/cli-hydrogen: patch
• skeleton: major

API Changes Overview

Change	Type	API	Priority	Issue	Status
cartDeliveryAddressesUpdate empty array support	Breaking Change	SFAPI	P0	#3273	Not Started
Gift card addition without replacement	New Feature	SFAPI	P1	#3271	Not Started
cartDeliveryAddressesReplace mutation	New Feature	SFAPI	P1	#3272	Not Started
@incontext visitorConsent for privacy	New Feature	SFAPI	P2	#3274	Not Started
Nested cart lines support	New Feature	SFAPI/CAAPI	P1	#3275	Not Started
Selling plan B2B warning code	New Feature	SFAPI	P2	#3276	Not Started
Merchandise not applicable error	New Feature	SFAPI	P2	#3277	Not Started
Image alt text translation	New Feature	SFAPI	P2	#3278	Not Started
Store credit company locations	New Feature	CAAPI	P2	#3279	Not Started
Payment schedule balance fields	New Feature	CAAPI	P2	#3280	Not Started

Status Key

• Not Started: Issue created, implementation tracked separately
• This PR: Foundation work (version update) complete

Breaking Changes

cartDeliveryAddressesUpdate Behavior Change (#3273)

• Impact: Empty array now clears all delivery addresses (previously ignored/errored)
• Action: Verify existing usage doesn't unintentionally pass empty arrays
• Priority: P0 - Must verify before merge

Validation Status

All Validation Passing

• TypeScript: No errors
• Tests: All passing (96 test files, 904+ tests)
• Lint: No issues
• Build: Successful

HOW to test your changes?

Verify Type Generation

cd packages/hydrogen-react
npm run graphql-types
cd ../..

Verify Builds

npm run build:pkg

Verify Tests

npm test
npm run typecheck
npm run lint

Verify Skeleton

cd templates/skeleton
npm run codegen
npm run build
cd ../..

Post-merge steps

After merging:

1. Wait for CI release PR creation - Changesets will create version PR
2. Implement P0 issue - Address [2025-10 SFAPI] BREAKING: cartDeliveryAddressesUpdate supports empty array to clear addresses #3273 breaking change verification
3. Implement P1 issues - Add new features [2025-10 SFAPI] Add support for gift card addition without replacement #3271, [2025-10 SFAPI] Add cartDeliveryAddressesReplace mutation #3272, [2025-10 SFAPI/CAAPI] Add support for nested cart lines #3275
4. Update changelog.json - After npm release, enable h2 upgrade command
5. Consider P2 issues - Can be follow-up PRs

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

Related Links

• 2025-10 API Changelog
• API Update Guide - Enhanced with package version update step

Files Changed

53 files changed: +293 insertions, -117 deletions

Commits

• e610200b5 - API version update (48 files)
• 199a5db80 - Package version updates + guide enhancement (5 files)

[shopify]

Oxygen deployed a preview of your 2025-10-api-update branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	October 22, 2025 5:58 PM

Learn more about Hydrogen's GitHub integration.

[Copilot]

Pull Request Overview

This PR updates the Storefront API and Customer Account API from version 2025-07 to 2025-10, aligning with Shopify's latest quarterly API release. The update establishes the foundation for new features including nested cart lines, gift card operations, and delivery address management.

Key Changes:

• API version constants updated from 2025-07 to 2025-10 across all packages
• Package versions updated from 2025.7.0 to 2025.10.0 following the YYYY.MM.PATCH pattern
• Generated GraphQL types and schemas regenerated from 2025-10 API definitions

Reviewed Changes

Copilot reviewed 47 out of 53 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/hydrogen/src/version.ts	Updated package version constant to 2025.10.0
packages/hydrogen/src/storefront.ts	Updated API version references in documentation links
packages/hydrogen/src/react-router-preset.ts	Updated preset name and error messages to reference 2025.10.0
packages/hydrogen/src/react-router-preset.test.ts	Updated test expectations for new preset version
packages/hydrogen/src/product/getSelectedProductOptions.doc.ts	Updated Storefront API documentation link
packages/hydrogen/src/product/VariantSelector.ts	Updated deprecation notices and API documentation links
packages/hydrogen/src/exports.test.ts	Updated test expectation for preset name
packages/hydrogen/src/customer/customer-account-helper.test.ts	Updated Customer Account API version in tests
packages/hydrogen/src/customer/constants.ts	Updated default Customer Account API version constant
packages/hydrogen/src/createStorefrontClient.doc.ts	Updated documentation link reference
packages/hydrogen/src/context-keys.doc.ts	Updated internal documentation link
packages/hydrogen/src/cart/queries/*.doc.ts	Updated Storefront API object documentation links (8 files)
packages/hydrogen/src/cart/queries/cartMetafieldDeleteDefault.ts	Updated API mutation reference in code comment
packages/hydrogen-react/src/useMoney.tsx	Updated API version references in JSDoc comments
packages/hydrogen-react/src/useMoney.test.tsx	Updated test configuration API version
packages/hydrogen-react/src/useCartActions.tsx	Updated Cart API documentation links
packages/hydrogen-react/src/useCartAPIStateMachine.tsx	Updated Cart object documentation references
packages/hydrogen-react/src/storefront-client.test.ts	Updated test expectations for SDK version headers
packages/hydrogen-react/src/storefront-client.example.js	Updated example API version
packages/hydrogen-react/src/storefront-api-constants.ts	Updated SFAPI_VERSION constant to 2025-10
packages/hydrogen-react/src/optionValueDecoder.ts	Updated encoded variant field documentation links
packages/hydrogen-react/src/codegen.helpers.ts	Updated GraphQL scalars documentation references
packages/hydrogen-react/src/Video.tsx	Updated Video object documentation link
packages/hydrogen-react/src/ShopifyProvider.test.tsx	Updated test configuration and expectations
packages/hydrogen-react/src/ShopifyProvider.stories.tsx	Updated Storybook example version
packages/hydrogen-react/src/ShopPayButton2.example.*	Updated example configurations (2 files)
packages/hydrogen-react/src/Money.tsx	Updated MoneyV2 object documentation references
packages/hydrogen-react/src/ModelViewer.tsx	Updated Model3D object documentation link
packages/hydrogen-react/src/Image.tsx	Updated Image object documentation reference
packages/hydrogen-react/src/CartProvider.tsx	Updated Cart object documentation links
packages/hydrogen-react/src/CartProvider.stories.tsx	Updated Storybook configuration and comments
packages/hydrogen-react/src/CartLineProvider.tsx	Updated CartLine object documentation link
packages/hydrogen-react/docs/staticPages/hydrogenReact.doc.ts	Updated API client documentation link
packages/hydrogen-react/codegen.ts	Updated SF_API_VERSION and CA_API_VERSION constants
packages/cli/src/commands/hydrogen/upgrade.test.ts	Updated test fixture date
.claude/commands/apis-version-update.md	Enhanced documentation with package version update instructions
.changeset/api-update-2025-10.md	Added changeset documenting version bumps

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[kucherenko-ae]

hello
I've noticed that some utilities also need to be updated.

cart for example:
https://github.com/Shopify/hydrogen/blob/199a5db803f88cf021843b06715fdfd2c20131e5/packages/hydrogen/src/cart/createCartHandler.ts#L245C5-L258C7

to lines map need to add parent, for nested cart lines:

      const lines = linesWithOptimisticData.map((line) => {
        return {
          attributes: line.attributes,
          quantity: line.quantity,
          merchandiseId: line.merchandiseId,
          sellingPlanId: line.sellingPlanId,
          parent: line.parent
        };
      });

I haven't dug deeper yet, this is actually what I stumbled upon in the new project =D