[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 #3273 breaking change verification
3. Implement P1 issues - Add new features #3271, #3272, #3275
4. Update changelog.json - After npm release, enable h2 upgrade command
5. Consider P2 issues - Can be follow-up PRs

Checklist

• [x] I've read the Contributing Guidelines
• [x] I've considered possible cross-platform impacts (Mac, Linux, Windows)
• [x] I've added a changeset if this PR contains user-facing or noteworthy changes
• [x] I've added tests to cover my changes
• [x] 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)