[2025-07] Handle cart warnings for non-applicable discount codes

[juanpprieto]

Context

As of API version 2025-07, the Storefront API's Cart object now provides detailed warnings for non-applicable discount codes through the new CartWarning types.

Required Changes

• Update cart components to handle and display CartWarning messages
• Create UI components for showing discount warning messages
• Add logic to parse different warning types and provide user-friendly messages
• Update cart utilities to check for warnings on discount codes

Technical Details

Previously, non-applicable discount codes only returned applicable: false with no details. Now the API provides specific reasons why a discount code isn't applicable through CartWarning types.

Key Files to Update

• packages/hydrogen/src/cart/queries/cart-fragments.ts - Add warnings field to cart fragments
• packages/hydrogen/src/cart/CartProvider.tsx - Handle warnings in cart context
• packages/hydrogen/src/cart/optimistic/useOptimisticCart.tsx - Include warnings in optimistic updates
• packages/hydrogen-react/src/storefront-api-types.ts - Generated types will include CartWarning
• templates/skeleton/app/components/Cart.tsx - Example implementation of warning display
• packages/hydrogen/src/cart/types.ts - Add TypeScript interfaces for warning handling

Why These Files

• cart-fragments.ts: GraphQL fragments used by all cart queries need the warnings field
• CartProvider.tsx: Central state management for cart data including warnings
• useOptimisticCart.tsx: Ensures warnings are preserved during optimistic updates
• Cart.tsx skeleton: Provides a reference implementation for developers
• types.ts: Type safety for warning-related functions and components

Implementation Suggestions

// Example of handling cart warnings
function getDiscountWarnings(cart: Cart) {
  return cart.discountCodes
    .filter(code => \!code.applicable)
    .map(code => ({
      code: code.code,
      warnings: cart.warnings?.filter(w => w.target === code.code)
    }));
}

References

• CartWarning documentation
• API Changelog

Related PR

• API version update PR: #[pending]