Catalogue, cart and checkout

01The catalogue: products, variants and attributes

Think of a product as a shelf label ("Nail polish") and a variant as the actual thing you put in a box ("Nail polish, red, 15 ml"). Customers browse products, but you sell, stock and price variants — each variant has its own SKU (stock-keeping unit, a unique code), price and stock. Attributes describe variants: colour, size, weight, flavour. Grouping attributes into attribute families ("clothing" has size and colour, "pet food" has weight and flavour) keeps the admin sane. Categories form a tree (Dogs → Food → Dry food); store them with a nested-set or a parent_id plus a cached path so "all products under Dogs" is one query. Brands, tags and collections are separate many-to-many links, not more categories.

• Product: name, description, images, SEO fields, category links.
• Variant: SKU, attribute values, price, weight, barcode, stock link.
• Some goods are sold by pack or by weight — model the sale unit explicitly instead of hacking quantities.

02Money: integers, currencies and taxes

Never store money as a float. 0.1 + 0.2 is not 0.3 in binary floating point, and those tiny errors add up into real accounting differences. Store amounts as integers in the smallest unit (cents, or whole drams for currencies without minor units) together with an ISO 4217 currency code, and do arithmetic with a money library or value object. Decide once whether catalogue prices include tax (common for consumer shops in Europe, Armenia and Australia) or exclude it (common in the US), and calculate tax per line with a clear rounding rule. Save a snapshot of every price, discount and tax on the order line: the catalogue will change tomorrow, but the order must still show what the customer paid.

1// Money as a small value object: integer minor units + currency
2type Money = { amount: number; currency: "USD" | "EUR" | "AMD" };
3 
4const add = (a: Money, b: Money): Money => {
5  if (a.currency !== b.currency) throw new Error("Currency mismatch");
6  return { amount: a.amount + b.amount, currency: a.currency };
7};
8 
9// Tax included in the price: extract it with one explicit rounding rule
10const taxIncluded = (gross: Money, ratePercent: number): Money => ({
11  amount: Math.round((gross.amount * ratePercent) / (100 + ratePercent)),
12  currency: gross.currency,
13});
14 
15const line = { amount: 1999, currency: "USD" } as const; // $19.99
16console.log(taxIncluded(line, 20)); // { amount: 333, currency: "USD" }

03The cart: guests, merging and validation

Let people shop without an account. A guest cart lives on the server, identified by a random token stored in a cookie (web) or secure storage (app). Keeping it server-side means prices and rules are calculated in one place, and the cart follows the user across devices once they log in. When a guest signs in, merge: add guest lines to the account cart, combine quantities for the same variant, then delete the guest cart. Treat the cart as a wish, not a promise. Every time it is read — and always at checkout — re-validate it: is the variant still active, is there enough stock, has the price changed, is the branch open, is the minimum order met? Return clear messages ("Price changed from 12.00 to 13.50") instead of silently fixing things.

• Store variant IDs and quantities in the cart, never trusted prices from the client.
• Recalculate totals on the server for every response.
• Offer reorder: copy lines from a past order into the cart, then validate as usual.

04Checkout and the order state machine

Checkout collects what the order needs — contact, address or pickup point, delivery slot, payment method — then creates the order in one database transaction: copy cart lines with price snapshots, reserve stock, store totals, and set status to pending payment. From then on, the order moves through an explicit state machine. A state machine is simply a list of allowed statuses and allowed moves between them. Writing it down prevents nonsense like a cancelled order becoming delivered, and every move is logged in a status history table with who and when. Side effects — emails, push, kitchen screens, ERP export — hang off transitions, ideally through queued jobs.

1const transitions = {
2  pending_payment: ["paid", "cancelled"],
3  paid: ["preparing", "refunded"],
4  preparing: ["ready", "cancelled"],
5  ready: ["out_for_delivery", "picked_up"],
6  out_for_delivery: ["delivered", "failed_delivery"],
7  delivered: ["refunded"],
8} as const;
9 
10type Status = keyof typeof transitions | "cancelled" | "refunded" | "picked_up" | "failed_delivery";
11 
12export function canMove(from: Status, to: Status): boolean {
13  const allowed = (transitions as Record<string, readonly string[]>)[from] ?? [];
14  return allowed.includes(to);
15}

05Delivery, pickup and time slots

Fulfilment is where shops differ most. Delivery needs an address, a zone and a fee. Zones are usually polygons on a map: geocode the address to coordinates, then check which polygon contains the point to get the fee, minimum order and serving branch. Pickup (takeaway) needs a branch and maybe a product list that differs per branch. Time slots turn opening hours into choosable windows: ASAP, or scheduled in 15- or 30-minute steps, respecting preparation time, closing time and a "business day" that may end after midnight. Generate slots on the server, in the shop's time zone, and validate the chosen slot again at checkout — a slot that was free when the page loaded may be gone a minute later.

06Preventing overselling and sending the right emails

Overselling happens when two customers buy the last item at the same moment. The fix is to make the stock change atomic. Either lock the row (SELECT … FOR UPDATE inside a transaction) or use a conditional update that only succeeds if enough stock remains, and check the number of affected rows. Reserve stock when the order is created and release it if payment fails or times out; a scheduled job cancels abandoned pending orders. Transactional emails — order received, paid, shipped, refunded — should be sent from a queue after the transaction commits, so a slow mail server never blocks checkout and no email is sent for an order that was rolled back.

1-- Atomic decrement: succeeds only when enough stock is left
2UPDATE stock_levels
3SET quantity = quantity - 2
4WHERE variant_id = 42
5  AND warehouse_id = 1
6  AND quantity >= 2;
7-- 1 row affected → reserved; 0 rows → out of stock, tell the customer

07Idempotent order creation: surviving double clicks and retries

A customer taps "Place order" twice, a mobile app retries after a timeout, a load balancer replays a request. Without protection each of these can create a second order and reserve stock twice. The fix is a checkout key: the client generates a random UUID when the checkout screen opens and sends it with the submit request. The server stores it on the order under a unique constraint. The first request creates the order; any repeat with the same key returns the existing order instead of creating a new one. Keep the key for the life of that checkout attempt and generate a fresh one only when the cart changes. Pair it with a short per-cart lock (a Redis lock or an advisory lock) so two parallel requests do not both pass validation before either inserts.

1-- One order per checkout attempt, enforced by the database
2ALTER TABLE orders ADD COLUMN checkout_key UUID;
3CREATE UNIQUE INDEX orders_checkout_key_uq ON orders (checkout_key);
4 
5-- Inside the checkout transaction
6INSERT INTO orders (checkout_key, customer_id, status, total_amount, currency)
7VALUES ($1, $2, 'pending_payment', $3, $4)
8ON CONFLICT (checkout_key) DO NOTHING
9RETURNING id;
10-- No row returned → a previous request already created it:
11-- SELECT id FROM orders WHERE checkout_key = $1 and return that order.

08Allocating discounts and rounding without losing a cent

A cart-level discount ("5.00 off the order") must be split across lines, because tax, refunds and ERP exports work per line. Split it proportionally to each line's value, round each share down, then give the leftover cents to the lines with the largest remainders. The shares always add up to the exact discount, and a later partial refund of one line returns precisely what that line was charged. Also respect the currency's minor unit from ISO 4217: most currencies have 2 decimals, the Japanese yen has 0, and the Kuwaiti dinar has 3. Never hard-code "divide by 100". For multi-currency stores, snapshot the exchange rate on the order, and decide whether you convert prices (display currency) or actually charge in that currency (settlement currency).

1// Split an integer amount across weights; parts always sum to the total
2export function allocate(total: number, weights: number[]): number[] {
3  const sum = weights.reduce((a, b) => a + b, 0);
4  const raw = weights.map((w) => (total * w) / sum);
5  const parts = raw.map(Math.floor);
6  let rest = total - parts.reduce((a, b) => a + b, 0);
7  const order = raw
8    .map((r, i) => ({ i, frac: r - Math.floor(r) }))
9    .sort((a, b) => b.frac - a.frac);
10  for (const { i } of order) {
11    if (rest-- <= 0) break;
12    parts[i] += 1;
13  }
14  return parts;
15}
16 
17allocate(500, [1999, 999, 2]); // [333, 167, 0] → sums to 500

09Read models for fast catalogue pages

A category page that joins products, variants, prices, stock, images and promotions on every request becomes slow as the catalogue grows. The usual answer is a read model: a denormalised table (or search index document) with one row per product holding exactly what the listing needs — minimum price, in-stock flag, main image, attribute values for filters, rating. Background jobs update it when the source data changes, and the storefront reads only this table. Cache rendered fragments or API responses with tags so a price change invalidates just the affected products. Keep the write model (normalised tables, transactions) as the source of truth; the read model can always be rebuilt from it. This split, sometimes called CQRS (command query responsibility segregation), lets reads scale without complicating checkout.

• Rebuild a product's read row in a queued job after price, stock or content changes.
• Paginate listings with keyset pagination (WHERE id > last_id) for deep pages.
• Never compute live promotion prices for every product on a listing; precompute badges.

10Security edge cases in carts and orders

Carts and orders are classic targets for insecure direct object references (IDOR): changing /orders/1042 to /orders/1043 and seeing someone else's order. Use unguessable public identifiers (UUIDs or random tokens) in URLs and always scope queries by the owner. Rotate the guest cart token when the user logs in, so a token captured before login cannot be used to read the account cart. Validate quantities as positive integers with an upper limit — negative quantities have produced real refunds in poorly built shops. Rate-limit coupon and checkout endpoints to slow down brute force and card testing, where attackers run stolen cards through small orders. Finally, keep personal data in orders minimal and plan how long you retain it, because order tables quietly become your largest store of personal data.