id: carts
type: concept
owner: justin
component: storefront-api
describes:
  - src/carts.ts
  - src/money.ts
  - migrations/0002_carts.sql
reviewed: 2026-10-01

Carts

A cart is a row in carts and its lines in cart_items. Anyone can create one with POST /carts; the id is a random UUID, and knowing it is what gives access to the cart.

Setting quantities

PUT /carts/:id/items/:product with { "quantity": n } sets how many of a product the cart holds. It sets rather than adds, so a client that retries after a timeout does not double the quantity. Zero, or DELETE on the same path, removes the line.

The limits:

• at most 10 of one product and 50 different products per cart;
• never more than the product's current stock (the error says how many are left);
• only active products, and only while the cart is open.

Setting a quantity checks stock but does not hold it. Stock is only taken when the cart is checked out.

Prices and totals

Each line stores unit_price_cents, the product's price when the quantity was last set. totals() in src/money.ts adds the lines and a flat shipping rate of $5.95 for subtotals under $50; from $50 shipping is free. All of it is whole cents ([[0003-money-in-whole-cents]]).