Commerce
Shopping Cart
Lets users add products, change quantities, and review their selection before checkout. Persists across sessions.
When to use this
When users buy multiple items in one transaction. Skip this pattern for single-item purchases (use checkout directly).
What I assumed
I made these guesses to fill gaps. Let me know if any are wrong.
Flow diagram
Step-by-step recipe
Copy this and paste into Cursor, Claude Code, or v0.
PATTERN: Shopping Cart
INPUT: product_id, quantity (per add action)
OUTPUT: cart_state (list of items with totals)
STEPS:
1. User browses products
2. User clicks "Add to cart" on a product
3. IF item already in cart → increment quantity, otherwise add new line
4. Persist cart (logged-in: DB; guest: localStorage + cookie)
5. Show cart count badge update with brief animation
6. User opens cart view
7. User changes quantity or removes items
8. Recalculate subtotal, tax, shipping estimate on each change
9. User clicks "Checkout"
10. Verify all items still available and prices unchanged (re-fetch)
11. IF something changed → show "Some items changed, please review" banner
12. Hand off to checkout flow
ERROR_HANDLING:
- Item out of stock when adding → show "Only N left" or "Sold out, want notification?"
- Price changed since adding → show old vs new price, let user decide
- Cart sync conflict (multi-device) → use "last write wins" or merge by max quantity
- User signs in with existing cart → merge guest cart + saved cart
EXTENSION_POINTS:
- Apply coupon codes (composable_with: ["coupon"])
- Real-time inventory check (composable_with: ["inventory-check"])
- Save for later (composable_with: ["wishlist"])
- Guest checkout without account (composable_with: ["guest-checkout"])
States — how things change
| State | Description | Transitions |
|---|---|---|
| Cart empty | User has not added anything yet |
|
| Cart has items | One or more items in cart; user can edit |
|
| Validating cart | Re-fetching availability and prices |
|
| Handed off to checkout | User is now in the checkout flow | terminal |
Easy-to-miss situations
The kinds of edge cases that break demos.
What if the user adds 100 of an item by mistake?
lowTriggers high-value validation, possibly a fraud flag.
Suggested handling: Cap quantity per item (e.g., max 10) with override request flow for legitimate bulk buyers.
What if the user adds items on phone, then opens laptop?
mediumCart should sync if logged in. If guest, cart is device-local and won't appear.
Suggested handling: For guests, prompt "Save this cart? Sign up to access from any device." Make logged-in cart sync near-real-time.
What if an item goes out of stock between cart and checkout?
highEspecially common for limited drops or flash sales.
Suggested handling: Re-validate at checkout entry. Show "Sorry, [item] just sold out. Continue with the rest?" Don't silently remove.
What if the user signs in mid-shopping?
mediumThey might already have a saved cart from before — merging matters.
Suggested handling: Merge by max quantity per item. Show a brief "We combined your cart with your saved items" toast.
What if prices change while items are in the cart?
highEspecially during sales — user might be confused or feel cheated.
Suggested handling: Show old vs new price clearly with badge. If price went up, ask user to confirm. If down, just apply the lower price quietly (good UX).
Composes well with
Combine these patterns when you need a richer flow.