System Design: [Commerce platform name] cart, checkout and inventory

Reference design for the cart, checkout and inventory core of an online store or multi-merchant commerce platform. It covers cart storage, price and tax quotes with clear boundaries to pricing, tax and promotion services, stock reservation across warehouses, oversell prevention, the payment handoff, the order state machine, and flash-sale throttling with a checkout queue. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Replace every [bracketed] value and every row marked Example; values marked Example are assumptions, not benchmarks. This is an engineering format, not tax, consumer-protection or payment-compliance advice.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: We run 40 000 stores on one platform. During a sneaker drop last spring one store sold 1 400 pairs it did not have, because stock was decremented after payment and two checkout pods read the same count. The same drop sent write traffic to the shared order database that slowed checkout for every store on that shard for 25 minutes. Promotions are computed in three places, so the cart, the review page and the receipt sometimes show different totals, and support refunds the difference by hand.]

1.2 Proposed solution

[Example: A quote service is the only place that computes a total: it calls pricing, promotions and tax and returns a signed, versioned quote. Checkout reserves stock for the quoted lines with a conditional decrement and a 10-minute expiry when the customer starts checkout. Payment is authorised against the quote; the order is created in placed and moves through an explicit state machine to fulfilment. Stock is held per SKU and location in an inventory service partitioned by SKU. Flash sales are recognised ahead of time; a throttle at the edge admits shoppers into checkout at the rate the hot SKU partition and the payment provider can absorb, and everyone else waits on a cached queue page.]

1.3 Decisions requested from reviewers

1.4 45-minute interview path

2. Requirements

2.1 Core functional requirements

2.2 Non-functional requirements and invariants

2.3 Below the line (out of scope)

• [Example: product search and recommendations (see Recommendation System Design (system-design/design-recommendation-system))]
• [Example: pricing algorithms and promotion authoring (consumed through the quote boundary)]
• [Example: tax rule content (consumed from a tax engine)]
• [Example: returns and exchanges workflow]
• [Example: the payment ledger (see Payment Ledger System Design (system-design/design-payment-ledger))]
• [Example: warehouse management and picking]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Normal traffic

3.3 Flash-sale traffic

3.4 Storage

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

POST /v1/checkouts/chk_31b9/place-order
Idempotency-Key: 0d9e6f12-7a44-4c1b-8e3f-5b2a9c7d1e08
Authorization: Bearer [token]
Content-Type: application/json

{"quote_id": "q_31b9_v3", "payment_method": "pm_tok_8f2", "accepted_total": {"value": 12999, "currency": "USD"}}

HTTP/1.1 201 Created
Content-Type: application/json

{"order_id": "ord_7e21", "status": "placed", "total": {"value": 12999, "currency": "USD"}}

The client sends the total it displayed. If the server's quote total differs, place-order fails with 409 quote-changed and returns the new quote, so the customer is never charged an amount they did not see (NFR-02).

4.3 Errors

Errors use RFC 9457 problem details.

5. Data model

5.1 Entities

The cart is indicative and cheap; the quote, reservation and order are authoritative. Stock is counted inventory, one row per SKU and location.

5.2 Storage choices and invariants

5.3 Access patterns

6. High-level design

7. Detailed design

7.1 Quote boundary: pricing, tax and promotions

• The quote service owns the arithmetic: list price from pricing, discounts from promotions in a fixed evaluation order, shipping, then tax on the discounted amounts according to the tax engine's rules.
• A quote is immutable. Any change (address, shipping, quantity) creates a new version. The quote records the versions of the price list, promotion set and tax rules it used.
• Promotions with limited redemptions (first 1 000 uses) are reserved like stock at checkout start and committed at order placement.
• Rounding happens once, in the quote, per the tax engine's rule (per line or per invoice). No other service rounds.

Options: compute totals in checkout; compute in each service and sum; central quote. Choice: central quote. Reason: one place to test and audit totals, and NFR-02 becomes a comparison of two numbers.

7.2 Deep dive: when to reserve stock

Choice: reserve at checkout start with a Example 10-minute TTL, extendable once during 3-D Secure, and re-validate the reservation at place-order. Reason: it binds stock to real intent, bounds waste and lets the cart stay a cheap, non-authoritative store.

7.3 Deep dive: oversell prevention under contention

Choice: conditional decrement by default; sharded counters (Example K = 8) for SKUs flagged as drops. Reason: 750 writes/s on one row (3.3) exceeds a safe row update rate, while 8 buckets bring each to about 95 writes/s. When most buckets are empty, a final pass merges remaining units into one bucket so the last items still sell.

UPDATE stock_bucket
SET reserved = reserved + :qty, version = version + 1
WHERE sku = :sku AND bucket = :b
  AND reserved + :qty <= on_hand;
-- 0 rows: try next bucket; after K misses return 409 out-of-stock.

7.4 Deep dive: payment handoff and order state machine

Place-order sequence:

• Options for capture: at order placement; at shipment; split capture per shipment. Choice: capture at shipment for physical goods, at placement for digital goods. Reason: the shopper is never charged for items that cannot ship, and cancellations before shipment are voids, not refunds. Check the authorisation validity period of your card networks and re-authorise if fulfilment is slow.
• An order that cannot commit its reservations after authorisation (expired meanwhile) attempts to re-reserve; on failure it voids the authorisation and returns 410.
• Every transition writes an order_event and an outbox row in one transaction; illegal transitions are rejected by a transitions table.

7.5 Deep dive: flash-sale throttling

Choice: edge throttle with a cached queue page and a signed pass, plus randomised positions for drops announced in advance. Reason: it caps checkout writes per store at the admission rate in 3.3, keeping other tenants within NFR-05, and the queue page costs the origin nothing.

How real systems do it (paraphrased from a public write-up; not copied)

Shopify's engineering blog describes how flash sales on a shared multi-tenant platform produced bursts of checkout writes large enough to hurt other stores on the same database shard. Rather than keep enough capacity running for the worst sale, the team put scripted logic into its Nginx load balancers (OpenResty with Lua): a leaky-bucket style throttle admitted a fixed number of checkout requests per short interval, sent the rest to a queue page cached at the load balancer that polled for entry, and gave admitted shoppers a signed cookie so they were not throttled again during their session. The post is candid that random polling made waits unfair for some shoppers, which led to a later redesign. This template keeps the edge throttle and signed pass and adds ordered or randomised positions to address fairness.

Source: Emil Stolarsky, "Surviving Flashes of High-Write Traffic Using Scriptable Load Balancers (Part I)", Shopify Engineering, 3 February 2017, https://shopify.engineering/surviving-flashes-of-high-write-traffic-using-scriptable-load-balancers-part-i

7.6 Multi-location allocation

The inventory service picks a location at reservation time using a simple rule (Example: nearest location with full quantity, else split shipment if the store allows it). Fulfilment may reallocate later; reallocation moves the reservation between rows of the same SKU on the same shard.

8. Scalability and performance

Latency budget for place-order (p99 target 1.2 s):

9. Reliability, security and operations

9.1 Failure modes

Score these in a Software FMEA (ops/fmea-software).

9.2 Security and abuse

9.3 Observability

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Enable reservations per store cohort behind a flag. Rollback returns the cohort to decrement-at-order with conditional writes, which is still oversell-safe. Drops are only run on stores already migrated.]

11.3 Risks

12. Appendices

12.1 Traceability

12.2 Open questions

12.3 Glossary

12.4 References

Standard and licence note

Based on common industry practice for commerce checkout and inventory systems and on the public references in 12.4. Company blogs were used as inspiration only; the text, diagrams and numbers are original and illustrative. Tax, consumer-protection and card-network rules vary by jurisdiction and change; check the current official rules. This is an engineering format, not legal advice. Template licence: MIT.