Design Amazon Shopping Cart

1
GET /api/v1/cart
2
Authorization: Bearer {token} | X-Guest-Token: {guest_token}

1
{
2
  "cart_id": "cart_abc123",
3
  "user_id": "user_xyz789",
4
  "items": [
5
    {
6
      "item_id": "item_001",
7
      "product_id": "prod_12345",
8
      "product_name": "Wireless Headphones",
9
      "variant_id": "var_black_medium",
10
      "quantity": 2,
11
      "unit_price": 79.99,
12
      "line_total": 159.98,
13
      "image_url": "https://cdn.example.com/headphones.jpg",
14
      "availability": {
15
        "status": "in_stock",
24 collapsed lines
16
        "quantity_available": 45,
17
        "reservation_expires_at": "2024-01-15T10:35:00Z"
18
      },
19
      "applied_promotions": [
20
        {
21
          "promotion_id": "promo_winter_sale",
22
          "name": "Winter Sale 20% Off",
23
          "discount_amount": 31.99
24
        }
25
      ]
26
    }
27
  ],
28
  "summary": {
29
    "subtotal": 159.98,
30
    "discount_total": 31.99,
31
    "shipping_estimate": 0.0,
32
    "tax_estimate": 10.24,
33
    "total": 138.23
34
  },
35
  "applied_coupons": [],
36
  "created_at": "2024-01-15T09:00:00Z",
37
  "updated_at": "2024-01-15T10:30:00Z",
38
  "expires_at": "2024-02-14T09:00:00Z"
39
}

1
POST /api/v1/cart/items
2
Authorization: Bearer {token} | X-Guest-Token: {guest_token}
3
Content-Type: application/json
4
Idempotency-Key: {uuid}

1
{
2
  "product_id": "prod_12345",
3
  "variant_id": "var_black_medium",
4
  "quantity": 2
5
}

1
{
2
  "item_id": "item_001",
3
  "product_id": "prod_12345",
4
  "quantity": 2,
12 collapsed lines
5
  "unit_price": 79.99,
6
  "line_total": 159.98,
7
  "reservation": {
8
    "reservation_id": "res_abc123",
9
    "expires_at": "2024-01-15T10:35:00Z"
10
  },
11
  "cart_summary": {
12
    "item_count": 2,
13
    "subtotal": 159.98,
14
    "total": 138.23
15
  }
16
}

1
PATCH /api/v1/cart/items/{item_id}

1
{
2
  "quantity": 3
3
}

1
POST /api/v1/cart/coupons

1
{
2
  "code": "SAVE20"
3
}

1
{
2
  "coupon": {
3
    "code": "SAVE20",
4
    "description": "20% off your order",
5
    "discount_type": "percentage",
6
    "discount_value": 20,
7
    "applied_discount": 27.99
8
  },
9
  "cart_summary": {
10
    "subtotal": 159.98,
11
    "discount_total": 59.98,
12
    "total": 110.24
13
  }
14
}

1
POST /api/v1/checkout
2
Authorization: Bearer {token}

1
{
2
  "cart_id": "cart_abc123"
3
}

1
{
2
  "checkout_id": "checkout_xyz789",
3
  "status": "pending",
4
  "cart_snapshot": {
5
    "items": [...],
6
    "summary": {...}
5 collapsed lines
7
  },
8
  "required_steps": ["address", "payment", "review"],
9
  "completed_steps": [],
10
  "expires_at": "2024-01-15T11:00:00Z"
11
}

1
PUT /api/v1/checkout/{checkout_id}/address

1
{
2
  "shipping_address": {
3
    "name": "John Doe",
4
    "line1": "123 Main St",
5
    "line2": "Apt 4B",
6
    "city": "Seattle",
7
    "state": "WA",
8
    "postal_code": "98101",
9
    "country": "US",
10
    "phone": "+1-206-555-0123"
11
  },
12
  "billing_same_as_shipping": true
13
}

1
POST /api/v1/checkout/{checkout_id}/complete
2
Idempotency-Key: {uuid}

1
{
2
  "payment_method_id": "pm_card_visa_4242",
3
  "accept_terms": true
4
}

1
{
2
  "order_id": "order_abc123",
3
  "status": "confirmed",
4
  "confirmation_number": "AMZ-2024-ABC123",
5
  "estimated_delivery": "2024-01-18",
6
  "total_charged": 138.23,
7
  "payment": {
4 collapsed lines
8
    "method": "Visa ending in 4242",
9
    "transaction_id": "txn_xyz789"
10
  }
11
}

5 collapsed lines
1
-- Cart table
2
CREATE TABLE carts (
3
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
4
    user_id UUID REFERENCES users(id),
5
    guest_token VARCHAR(64) UNIQUE,
6
    status VARCHAR(20) DEFAULT 'active',
7
    created_at TIMESTAMPTZ DEFAULT NOW(),
8
    updated_at TIMESTAMPTZ DEFAULT NOW(),
9
    expires_at TIMESTAMPTZ,
10
    merged_into_cart_id UUID REFERENCES carts(id),
11

12
    CONSTRAINT user_or_guest CHECK (
13
        (user_id IS NOT NULL AND guest_token IS NULL) OR
14
        (user_id IS NULL AND guest_token IS NOT NULL)
15
    )
16
);
17

18
-- Cart items table
19
CREATE TABLE cart_items (
20
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
21
    cart_id UUID NOT NULL REFERENCES carts(id) ON DELETE CASCADE,
22
    product_id UUID NOT NULL,
23
    variant_id UUID NOT NULL,
24
    quantity INT NOT NULL CHECK (quantity > 0),
15 collapsed lines
25
    unit_price_at_add DECIMAL(10,2) NOT NULL,
26
    reservation_id UUID,
27
    added_at TIMESTAMPTZ DEFAULT NOW(),
28
    updated_at TIMESTAMPTZ DEFAULT NOW(),
29

30
    UNIQUE (cart_id, product_id, variant_id)
31
);
32

33
-- Indexes for common access patterns
34
CREATE INDEX idx_carts_user ON carts(user_id) WHERE user_id IS NOT NULL;
35
CREATE INDEX idx_carts_guest ON carts(guest_token) WHERE guest_token IS NOT NULL;
36
CREATE INDEX idx_carts_expires ON carts(expires_at) WHERE status = 'active';
37
CREATE INDEX idx_cart_items_cart ON cart_items(cart_id);
38
CREATE INDEX idx_cart_items_reservation ON cart_items(reservation_id)
39
    WHERE reservation_id IS NOT NULL;

1
# Cart metadata (Hash)
2
HSET cart:{cart_id}
3
    user_id "user_xyz789"
4
    item_count 3
5
    subtotal 259.97
6
    updated_at 1705312200
7

8
# Cart items (Hash - one per item)
9
HSET cart:{cart_id}:item:{item_id}
10
    product_id "prod_12345"
11
    variant_id "var_black_medium"
12
    quantity 2
13
    unit_price 79.99
14
    reservation_id "res_abc123"
15
    reservation_expires 1705312500
16

17
# Guest token to cart mapping
18
SET guest:{guest_token} cart_abc123 EX 2592000  # 30 days
19

20
# Cart expiration sorted set (for cleanup workers)
21
ZADD cart_expirations 1705312500 cart_abc123

3 collapsed lines
1
-- Inventory by location
2
CREATE TABLE inventory_entries (
3
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
4
    product_id UUID NOT NULL,
5
    variant_id UUID NOT NULL,
6
    location_id UUID NOT NULL,
7
    quantity_on_hand INT NOT NULL DEFAULT 0,
8
    quantity_reserved INT NOT NULL DEFAULT 0,
9
    quantity_available INT GENERATED ALWAYS AS
10
        (quantity_on_hand - quantity_reserved) STORED,
11
    updated_at TIMESTAMPTZ DEFAULT NOW(),
12

13
    UNIQUE (product_id, variant_id, location_id),
14
    CHECK (quantity_reserved <= quantity_on_hand)
15
);
16

17
-- Reservations table
18
CREATE TABLE inventory_reservations (
19
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
12 collapsed lines
20
    inventory_entry_id UUID NOT NULL REFERENCES inventory_entries(id),
21
    cart_id UUID NOT NULL,
22
    quantity INT NOT NULL,
23
    type VARCHAR(10) NOT NULL CHECK (type IN ('soft', 'hard')),
24
    created_at TIMESTAMPTZ DEFAULT NOW(),
25
    expires_at TIMESTAMPTZ,  -- NULL for hard reservations
26
    order_id UUID,  -- Set when converted to hard reservation
27

28
    INDEX idx_reservations_entry (inventory_entry_id),
29
    INDEX idx_reservations_cart (cart_id),
30
    INDEX idx_reservations_expires (expires_at) WHERE type = 'soft'
31
);

1
# Soft reservation with automatic expiry
2
SET reservation:{res_id}
3
    '{"inventory_entry_id":"inv_123","cart_id":"cart_abc","quantity":2}'
4
    EX 300  # 5 minutes
5

6
# Fast lookup: cart → reservations
7
SADD cart_reservations:{cart_id} res_001 res_002
8
EXPIRE cart_reservations:{cart_id} 300
9

10
# Fast lookup: inventory → reservations (for availability calculation)
11
SADD inventory_reservations:{inventory_entry_id} res_001 res_002
12
EXPIRE inventory_reservations:{inventory_entry_id} 300

15 collapsed lines
1
interface CartItem {
2
  productId: string
3
  variantId: string
4
  quantity: number
5
  reservationId?: string
6
}
7

8
interface MergeResult {
9
  mergedCart: Cart
10
  addedItems: CartItem[]
11
  updatedItems: Array<{ item: CartItem; previousQty: number }>
12
  conflicts: Array<{ guestItem: CartItem; reason: string }>
13
}
14

15
async function mergeGuestCart(
16
  userId: string,
17
  guestToken: string,
18
  strategy: "sum" | "max" | "keep_user" = "sum",
19
): Promise<MergeResult> {
20
  return await db.transaction(async (tx) => {
21
    // Load both carts with row-level locks
22
    const [userCart, guestCart] = await Promise.all([
23
      tx.query("SELECT * FROM carts WHERE user_id = $1 FOR UPDATE", [userId]),
24
      tx.query("SELECT * FROM carts WHERE guest_token = $1 FOR UPDATE", [guestToken]),
25
    ])
26

27
    if (!guestCart) {
28
      return { mergedCart: userCart, addedItems: [], updatedItems: [], conflicts: [] }
29
    }
30

31
    const result: MergeResult = {
32
      mergedCart: userCart || (await createUserCart(tx, userId)),
33
      addedItems: [],
34
      updatedItems: [],
35
      conflicts: [],
36
    }
37

38
    for (const guestItem of guestCart.items) {
39
      const existingItem = result.mergedCart.items.find(
40
        (i) => i.productId === guestItem.productId && i.variantId === guestItem.variantId,
41
      )
42

43
      if (!existingItem) {
44
        // Transfer item to user cart
21 collapsed lines
45
        await transferItem(tx, guestItem, result.mergedCart.id)
46
        result.addedItems.push(guestItem)
47
      } else {
48
        // Handle conflict based on strategy
49
        const newQty = resolveQuantity(existingItem.quantity, guestItem.quantity, strategy)
50
        const maxAllowed = await getMaxQuantity(guestItem.productId, guestItem.variantId)
51

52
        if (newQty > maxAllowed) {
53
          result.conflicts.push({
54
            guestItem,
55
            reason: `Quantity capped at ${maxAllowed} (max per order)`,
56
          })
57
        }
58

59
        if (newQty !== existingItem.quantity) {
60
          await updateItemQuantity(tx, existingItem.id, Math.min(newQty, maxAllowed))
61
          result.updatedItems.push({ item: existingItem, previousQty: existingItem.quantity })
62
        }
63

64
        // Release guest item's reservation (will be replaced by user cart's)
65
        if (guestItem.reservationId) {
66
          await releaseReservation(guestItem.reservationId)
67
        }
68
      }
69
    }
70

71
    // Mark guest cart as merged
72
    await tx.query("UPDATE carts SET status = $1, merged_into_cart_id = $2 WHERE id = $3", [
73
      "merged",
74
      result.mergedCart.id,
75
      guestCart.id,
76
    ])
77

78
    return result
79
  })
80
}
81

82
function resolveQuantity(userQty: number, guestQty: number, strategy: string): number {
83
  switch (strategy) {
84
    case "sum":
85
      return userQty + guestQty
86
    case "max":
87
      return Math.max(userQty, guestQty)
88
    case "keep_user":
89
      return userQty
90
  }
91
}

10 collapsed lines
1
enum CheckoutState {
2
  INITIATED = "initiated",
3
  CART_VALIDATED = "cart_validated",
4
  PAYMENT_AUTHORIZED = "payment_authorized",
5
  INVENTORY_RESERVED = "inventory_reserved",
6
  ORDER_CREATED = "order_created",
7
  PAYMENT_CAPTURED = "payment_captured",
8
  COMPLETED = "completed",
9
  COMPENSATION_REQUIRED = "compensation_required",
10
  FAILED = "failed",
11
}
12

13
interface CheckoutSaga {
14
  id: string
15
  cartId: string
16
  state: CheckoutState
17
  authorizationId?: string
18
  orderId?: string
19
  failedStep?: string
20
  compensationSteps: string[]
21
  createdAt: Date
22
  updatedAt: Date
23
}
24

25
async function executeCheckoutSaga(checkoutId: string): Promise<Order> {
26
  const saga = await loadSaga(checkoutId)
27

28
  try {
29
    // Each step is idempotent and checks current state before executing
30
    if (saga.state === CheckoutState.INITIATED) {
31
      await validateCart(saga)
32
      await transitionState(saga, CheckoutState.CART_VALIDATED)
33
    }
34

35
    if (saga.state === CheckoutState.CART_VALIDATED) {
36
      saga.authorizationId = await authorizePayment(saga)
37
      await transitionState(saga, CheckoutState.PAYMENT_AUTHORIZED)
38
    }
39

21 collapsed lines
40
    if (saga.state === CheckoutState.PAYMENT_AUTHORIZED) {
41
      await convertReservations(saga)
42
      await transitionState(saga, CheckoutState.INVENTORY_RESERVED)
43
    }
44

45
    if (saga.state === CheckoutState.INVENTORY_RESERVED) {
46
      saga.orderId = await createOrder(saga)
47
      await transitionState(saga, CheckoutState.ORDER_CREATED)
48
    }
49

50
    if (saga.state === CheckoutState.ORDER_CREATED) {
51
      await capturePayment(saga)
52
      await transitionState(saga, CheckoutState.PAYMENT_CAPTURED)
53
    }
54

55
    if (saga.state === CheckoutState.PAYMENT_CAPTURED) {
56
      await clearCart(saga)
57
      await transitionState(saga, CheckoutState.COMPLETED)
58
    }
59

60
    return await loadOrder(saga.orderId)
61
  } catch (error) {
62
    saga.failedStep = saga.state
63
    await transitionState(saga, CheckoutState.COMPENSATION_REQUIRED)
64
    await executeCompensation(saga)
65
    throw error
66
  }
67
}
68

69
async function executeCompensation(saga: CheckoutSaga): Promise<void> {
70
  // Compensate in reverse order of completed steps
71
  if (saga.orderId && saga.state !== CheckoutState.PAYMENT_CAPTURED) {
72
    await markOrderFailed(saga.orderId)
73
  }
74

75
  if (saga.state >= CheckoutState.INVENTORY_RESERVED) {
76
    await releaseHardReservations(saga.cartId)
77
  }
78

79
  if (saga.authorizationId) {
80
    await voidAuthorization(saga.authorizationId)
81
  }
82

83
  await transitionState(saga, CheckoutState.FAILED)
84
}

8 collapsed lines
1
interface IdempotencyRecord {
2
  key: string
3
  requestHash: string
4
  response: any
5
  statusCode: number
6
  createdAt: Date
7
  expiresAt: Date
8
}
9

10
async function withIdempotency<T>(
11
  key: string,
12
  request: any,
13
  handler: () => Promise<T>,
14
): Promise<{ result: T; statusCode: number; cached: boolean }> {
15
  const requestHash = hashRequest(request)
16

17
  // Check for existing response
18
  const existing = await redis.get(`idempotency:${key}`)
19
  if (existing) {
20
    const record: IdempotencyRecord = JSON.parse(existing)
21
    if (record.requestHash === requestHash) {
22
      return { result: record.response, statusCode: record.statusCode, cached: true }
23
    }
24
    // Same key, different request = error
25
    throw new ConflictError("Idempotency key reused with different request")
26
  }
27

28
  // Lock the key during processing
29
  const lockAcquired = await redis.set(
16 collapsed lines
30
    `idempotency:${key}`,
31
    JSON.stringify({ requestHash, status: "processing" }),
32
    "NX",
33
    "EX",
34
    300, // 5 minute lock
35
  )
36

37
  if (!lockAcquired) {
38
    // Another request is processing with same key
39
    throw new ConflictError("Request already in progress")
40
  }
41

42
  try {
43
    const result = await handler()
44
    const record: IdempotencyRecord = {
45
      key,
46
      requestHash,
47
      response: result,
48
      statusCode: 201,
49
      createdAt: new Date(),
50
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
51
    }
52

53
    await redis.set(`idempotency:${key}`, JSON.stringify(record), "EX", 86400)
54
    return { result, statusCode: 201, cached: false }
55
  } catch (error) {
56
    await redis.del(`idempotency:${key}`)
57
    throw error
58
  }
59
}

1
// ❌ Array-based: O(n) lookups for quantity updates
2
interface Cart {
3
  items: CartItem[]
4
}

1
// ✅ Normalized: O(1) lookups, efficient updates
2
interface CartState {
3
  items: Record<string, CartItem> // itemId → CartItem
4
  itemOrder: string[] // Maintains display order
5
  summary: CartSummary
6
  appliedCoupons: Coupon[]
7
  reservationTimers: Record<string, number> // itemId → expiresAt
8
}

10 collapsed lines
1
import { useMutation, useQueryClient } from "@tanstack/react-query"
2

3
function useAddToCart() {
4
  const queryClient = useQueryClient()
5

6
  return useMutation({
7
    mutationFn: addItemToCart,
8

9
    onMutate: async (newItem) => {
10
      // Cancel outgoing refetches
11
      await queryClient.cancelQueries({ queryKey: ["cart"] })
12

13
      // Snapshot previous state
14
      const previousCart = queryClient.getQueryData(["cart"])
15

16
      // Optimistically update
17
      queryClient.setQueryData(["cart"], (old: CartState) => ({
18
        ...old,
19
        items: {
20
          ...old.items,
21
          [newItem.itemId]: {
22
            ...newItem,
23
            status: "pending", // Visual indicator
24
          },
25
        },
26
        itemOrder: [...old.itemOrder, newItem.itemId],
27
        summary: recalculateSummary(old, newItem),
28
      }))
29

30
      return { previousCart }
31
    },
32

33
    onError: (err, newItem, context) => {
34
      // Rollback on error
35
      queryClient.setQueryData(["cart"], context.previousCart)
36
      showToast({
37
        type: "error",
38
        message: err.code === "INSUFFICIENT_STOCK" ? `Only ${err.available} available` : "Failed to add item",
39
      })
21 collapsed lines
40
    },
41

42
    onSuccess: (data, newItem) => {
43
      // Update with server response (includes reservation info)
44
      queryClient.setQueryData(["cart"], (old: CartState) => ({
45
        ...old,
46
        items: {
47
          ...old.items,
48
          [newItem.itemId]: {
49
            ...data.item,
50
            status: "confirmed",
51
          },
52
        },
53
        summary: data.cartSummary,
54
      }))
55
    },
56

57
    onSettled: () => {
58
      // Refetch to ensure consistency
59
      queryClient.invalidateQueries({ queryKey: ["cart"] })
60
    },
61
  })
62
}

5 collapsed lines
1
function useReservationTimer(expiresAt: string | null) {
2
  const [timeLeft, setTimeLeft] = useState<number | null>(null);
3
  const [isExpired, setIsExpired] = useState(false);
4

5
  useEffect(() => {
6
    if (!expiresAt) return;
7

8
    const updateTimer = () => {
9
      const remaining = new Date(expiresAt).getTime() - Date.now();
10
      if (remaining <= 0) {
11
        setIsExpired(true);
12
        setTimeLeft(0);
13
      } else {
14
        setTimeLeft(Math.ceil(remaining / 1000));
15
      }
16
    };
17

18
    updateTimer();
19
    const interval = setInterval(updateTimer, 1000);
20
    return () => clearInterval(interval);
21
  }, [expiresAt]);
22

23
  return { timeLeft, isExpired };
24
}
11 collapsed lines
25

26
// Usage in component
27
function CartItem({ item }: { item: CartItemData }) {
28
  const { timeLeft, isExpired } = useReservationTimer(item.reservationExpiresAt);
29

30
  return (
31
    <div className={isExpired ? 'item-expired' : ''}>
32
      {/* ... item display ... */}
33
      {timeLeft !== null && timeLeft < 300 && (
34
        <div className="reservation-warning">
35
          Reserved for {formatTime(timeLeft)} - complete checkout soon
36
        </div>
37
      )}
38
      {isExpired && (
39
        <div className="reservation-expired">
40
          Reservation expired - item may become unavailable
41
        </div>
42
      )}
43
    </div>
44
  );
45
}

10 collapsed lines
1
function useCartPriceSync(cartId: string) {
2
  const queryClient = useQueryClient()
3

4
  useEffect(() => {
5
    const ws = new WebSocket(`wss://api.example.com/cart/${cartId}/updates`)
6

7
    ws.onmessage = (event) => {
8
      const update = JSON.parse(event.data)
9

10
      switch (update.type) {
11
        case "price_change":
12
          queryClient.setQueryData(["cart"], (old: CartState) => {
13
            const item = old.items[update.itemId]
14
            if (!item) return old
15

16
            const priceDiff = update.newPrice - item.unitPrice
17
            return {
18
              ...old,
19
              items: {
20
                ...old.items,
21
                [update.itemId]: {
22
                  ...item,
23
                  unitPrice: update.newPrice,
24
                  lineTotal: update.newPrice * item.quantity,
25
                  priceChanged: priceDiff !== 0,
26
                  priceDiff,
27
                },
28
              },
29
              summary: recalculateSummary(old, update),
16 collapsed lines
30
            }
31
          })
32
          break
33

34
        case "item_unavailable":
35
          queryClient.setQueryData(["cart"], (old: CartState) => ({
36
            ...old,
37
            items: {
38
              ...old.items,
39
              [update.itemId]: {
40
                ...old.items[update.itemId],
41
                available: false,
42
                availableQuantity: update.availableQuantity,
43
              },
44
            },
45
          }))
46
          showToast({
47
            type: "warning",
48
            message: `${old.items[update.itemId].name} is now out of stock`,
49
          })
50
          break
51

52
        case "reservation_expired":
53
          queryClient.invalidateQueries({ queryKey: ["cart"] })
54
          break
55
      }
56
    }
57

58
    return () => ws.close()
59
  }, [cartId, queryClient])
60
}