[2025-07] Add cartGiftCardCodesRemove mutation support

[juanpprieto]

WHY are these changes introduced?

Addresses https://github.com/Shopify/hydrogen-internal/issues/231

The Storefront API 2025-07 release deprecated cartGiftCardCodesUpdate in favor of separate cartGiftCardCodesAdd and cartGiftCardCodesRemove mutations. This change addresses a critical UX issue where users couldn't remove individual gift cards when multiple were applied, since the API only returns the last 4 digits of gift card codes for security reasons.

WHAT is this pull request doing?

This PR adds support for the new cartGiftCardCodesRemove mutation to enable removing specific gift cards by their IDs.

Key Changes

Component	Change	Purpose
Cart Handler	Added removeGiftCardCodes method	Provides API to remove gift cards by ID
CartForm	Added GiftCardCodesRemove action	Enables form-based gift card removal
Cart Fragments	Added id field to appliedGiftCards	Required for removal operations
Skeleton Template	Added removal UI with individual remove buttons	Allows users to remove specific gift cards

Technical Details

• ✅ New mutation handler: cartGiftCardCodesRemoveDefault
• ✅ Maintains existing additive behavior for adding/updating gift cards
• ✅ Uses appliedGiftCardIds parameter (not giftCardCodes)
• ✅ Includes comprehensive tests without as any usage
• ✅ Updates both Hydrogen core and skeleton template

HOW to test your changes?

1. Start the skeleton dev server:

   cd templates/skeleton
   npm run dev

2. Add a product to the cart

3. Apply multiple gift cards

4. Verify:

   • Individual gift cards can be removed via their remove buttons
   • Adding new gift cards is still additive (doesn't replace existing ones)
   • Cart totals update correctly after removal
   • No console errors or React hooks violations

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

[shopify]

Oxygen deployed a preview of your feat-cartGiftCardCodesRemove branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	August 28, 2025 9:49 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	August 28, 2025 9:49 PM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	August 28, 2025 9:49 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	August 28, 2025 9:49 PM

Learn more about Hydrogen's GitHub integration.

[Copilot]

Pull Request Overview

This PR adds support for the new cartGiftCardCodesRemove mutation introduced in Storefront API 2025-07, addressing the inability to remove individual gift cards when multiple are applied to a cart.

• Added cartGiftCardCodesRemoveDefault mutation handler and corresponding cart method
• Added GiftCardCodesRemove action to CartForm for form-based gift card removal
• Updated cart fragments to include gift card id field required for removal operations

Reviewed Changes

Copilot reviewed 13 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
templates/skeleton/app/routes/cart.tsx	Added handler for GiftCardCodesRemove action
templates/skeleton/app/lib/fragments.ts	Added id field to appliedGiftCards fragment
templates/skeleton/app/components/CartSummary.tsx	Updated UI with individual remove buttons per gift card
packages/hydrogen/src/index.ts	Added export for cartGiftCardCodesRemoveDefault
packages/hydrogen/src/cart/queries/cartGiftCardCodesRemoveDefault.ts	New mutation handler implementation
packages/hydrogen/src/cart/queries/cartGiftCardCodesRemoveDefault.test.ts	Added test coverage for new mutation
packages/hydrogen/src/cart/queries/cartGiftCardCodesRemoveDefault.example.ts	TypeScript usage example
packages/hydrogen/src/cart/queries/cartGiftCardCodesRemoveDefault.example.js	JavaScript usage example
packages/hydrogen/src/cart/queries/cartGiftCardCodesRemoveDefault.doc.ts	Documentation configuration
packages/hydrogen/src/cart/queries/cartGetDefault.ts	Added appliedGiftCards to default cart fragment
packages/hydrogen/src/cart/createCartHandler.ts	Added removeGiftCardCodes method to HydrogenCart
packages/hydrogen/src/cart/CartForm.tsx	Added GiftCardCodesRemove action type and props
.changeset/gift-card-removal.md	Added changeset documentation

---

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