[2025-07] Display non-discount cart warnings in skeleton template

[juanpprieto]

Overview

The 2025-07 API update introduced new cart warning codes that are not currently displayed in the skeleton template. While PR #3084 handles discount-related warnings, there are additional warning codes that need to be displayed to users for better cart experience.

Affected Warning Codes

The following CartWarningCode enum values need user-friendly display:

• DUPLICATE_DELIVERY_ADDRESS - When adding a delivery address that already exists
• MERCHANDISE_NOT_ENOUGH_STOCK - When quantity exceeds available inventory (auto-adjusted)
• MERCHANDISE_OUT_OF_STOCK - When items become unavailable (removed from cart)
• PAYMENTS_GIFT_CARDS_UNAVAILABLE - When gift cards cannot be used for the order

Context

As of API version 2024-10, inventory errors about stock levels were moved from userErrors to warnings field in cart mutations. These warnings indicate that the mutation succeeded but the cart was automatically adjusted (e.g., quantities reduced to available stock or items removed).

Current State

• Cart route already captures warnings: const {cart: cartResult, errors, warnings} = result; (line 82 in app/routes/cart.tsx)
• CartWarnings component exists but only handles discount warnings (PR [2025-07] Display new Cart warnings in skeleton template #3084)
• Gift card functionality exists in CartSummary but doesn't handle the unavailable warning

Proposed Solution

1. Extend CartWarnings Component

Update app/components/CartWarnings.tsx to handle all warning types with appropriate messaging and actions:

const WARNING_MESSAGES: Partial<Record<CartWarningCode, string>> = {
  // Existing discount warnings...
  
  // Inventory warnings
  MERCHANDISE_NOT_ENOUGH_STOCK: 'Limited stock available - quantity has been adjusted',
  MERCHANDISE_OUT_OF_STOCK: 'This item is no longer available and has been removed',
  
  // Delivery warnings  
  DUPLICATE_DELIVERY_ADDRESS: 'This delivery address already exists in your cart',
  
  // Payment warnings
  PAYMENTS_GIFT_CARDS_UNAVAILABLE: 'Gift cards cannot be used for this order',
};

2. Add Contextual Actions

For certain warnings, provide actionable UI:

• Stock warnings: Show adjusted quantity or removed item details
• Duplicate address: Link to existing addresses
• Gift card: Explain restrictions or alternatives

3. Warning Severity Levels

Consider different visual treatments:

• Info (blue): DUPLICATE_DELIVERY_ADDRESS
• Warning (yellow): MERCHANDISE_NOT_ENOUGH_STOCK, PAYMENTS_GIFT_CARDS_UNAVAILABLE
• Error (red): MERCHANDISE_OUT_OF_STOCK

Files to Modify

1. templates/skeleton/app/components/CartWarnings.tsx - Add non-discount warning messages
2. templates/skeleton/app/components/CartLineItem.tsx - Potentially highlight affected items for stock warnings
3. templates/skeleton/app/components/CartSummary.tsx - Coordinate with gift card display

Testing Scenarios

1. Add items to cart, then reduce inventory in admin to trigger stock warnings
2. Add duplicate delivery addresses to trigger address warning
3. Test gift card restrictions based on cart contents/region
4. Verify warnings clear when issues are resolved

Dependencies

• Requires PR [2025-07] Display new Cart warnings in skeleton template #3084 to be merged first (discount warnings foundation)
• Part of 2025-07 API update

References

• Cart Warnings Documentation
• Related PR: [2025-07] Display new Cart warnings in skeleton template #3084 (Discount warnings)
• Parent PR: Add Storefront and Customer Account API version update command #3063 (2025-07 API update)

[juanpprieto]

This issue has been resolved as part of PR #3084, which now handles all cart warnings (both discount and non-discount warnings) in a single implementation.

The combined approach avoids code duplication and conflicts while providing complete cart warning support for all 16 warning codes.