cart-patterns

Cart Patterns

Cart State Management

Rule: Cart is server-authoritative

Never trust client-side cart state for pricing or inventory. The client holds product IDs and quantities; the server calculates everything else.

Client sends: { items: [{ productId: "abc", quantity: 2 }] }
Server returns: { items: [{ productId: "abc", quantity: 2, unitPrice: 29.99, lineTotal: 59.98, available: true }], subtotal: 59.98, tax: 5.40, total: 65.38 }

Rule: Use integers for money

Never use floating-point for currency. Store prices in the smallest currency unit (cents for USD, pence for GBP).

// WRONG
const price = 29.99;
const total = price * 3; // 89.97000000000001

// RIGHT
const priceInCents = 2999;
const totalInCents = priceInCents * 3; // 8997
const displayPrice = (totalInCents / 100).toFixed(2); // "89.97"

Rule: Validate inventory at checkout, not at cart-add

• Adding to cart: check inventory but don't reserve — show "low stock" warning if < 5 remaining
• Starting checkout: reserve inventory with a TTL (10-15 minutes)
• Completing payment: convert reservation to deduction
• Timeout/abandonment: release reservation

Rule: Idempotent cart operations

Cart mutations (add, remove, update quantity) must be idempotent. If a user clicks "Add to Cart" twice due to a slow network, they should get quantity 1 (or quantity+1 from current), not quantity 2.

Use: PUT /cart/items/{productId} with desired quantity, not POST /cart/items with delta.

Price Calculation

Order of operations (always this order):

1. Base price per item
2. Apply item-level discounts (sale prices, volume discounts)
3. Calculate line totals (price * quantity)
4. Calculate subtotal (sum of line totals)
5. Apply cart-level discounts (promo codes, loyalty points)
6. Calculate tax (on discounted subtotal, jurisdiction-dependent)
7. Add shipping
8. Calculate total

Discount rules

• Only one promo code at a time (unless explicitly supporting stacking)
• Validate promo code server-side: is it active? Has it expired? Has it hit its usage limit? Is the cart minimum met?
• Never expose discount calculation logic to the client — only the result
• Log every discount application for audit trail