Design an e-commerce checkout

The order is a promise. The server builds the order from the cart at submit time and never trusts prices sent by the browser. It reads the current price of every item, applies promotions and tax, adds shipping, and stores all of it as a snapshot on the order: lines, unit prices, discounts, tax, total and address. Later price changes cannot alter an order that exists.

If the snapshot differs from what the shopper last saw, the API refuses with the new total and the shopper confirms again. This keeps the charge equal to what they agreed to.

Idempotency. When the checkout page opens, the app makes a random key. Place order sends it. A unique constraint on the customer and the key in the Order DB means a second request, from a double click or a retry after a timeout, finds the first order and returns it. The order ID goes on to inventory and payment as their key.

The state machine. An order has a few states and only these moves: created, stock held, payment authorized, confirmed, shipped and completed, with failed and cancelled as exits. A change of state is a conditional update: 'set state to confirmed where state is payment authorized'. If no row changes, another worker got there first and this one stops. That makes the orchestrator safe to run twice, and it means an order can never be confirmed without stock held and payment authorized.

Store each move in a history table with a time and a reason. Support staff and the shopper's status page read from it.

Keep the answer fast. The API returns once the order row is saved, with the status 'processing', and the page learns the result by polling or a push. Waiting for three services inside the request would tie the shopper's request to the slowest of them.

A saga replaces it: a series of local transactions, each with a compensation that undoes it if a later step fails. With orchestration, one service, the orchestrator, holds the order's progress and tells each service what to do next.

• Reserve stock. Compensation: release the hold.
• Authorize payment, which sets money aside on the card without taking it. Compensation: void the authorization.
• Commit the hold, so it no longer expires. Compensation: release it.
• Confirm the order, then ask shipping to pack it. Compensation: cancel the shipment request, if the parcel has not left.
• On shipment, capture the payment. If the order is cancelled after that, the compensation is a refund.

Order the steps so the easiest to undo comes first and the hardest comes last. A stock hold is cheap and expires by itself. Taking money from a card is the hardest to take back. That is why we hold, then authorize, and capture only when the parcel ships.

Every step and every compensation must be safe to repeat, because messages arrive at least once and calls time out. Each call carries the order ID and the step name as its key. The receiver stores the result of the first call and replays it for repeats. A compensation must also cope with arriving before the thing it undoes. A release that arrives before the hold is recorded leaves a marker, so the late hold is ignored.

The outbox. The API and the orchestrator both change a row and publish an event. If they write the row and then publish, a crash between the two loses the event and the order stalls. If they publish first, they may announce a change that never committed. So they write the event into an outbox table in the same transaction as the state change. A relay reads the outbox and publishes, marking rows as sent. If the relay crashes it sends again, so consumers must be safe to repeat. A state change and its event now commit together or not at all.

Timeouts. A step that gets no answer is retried with the same key. A sweeper looks for orders stuck in a non-final state for 15 minutes, and drives each one to failed by running the compensations.

A hold is one conditional update, 'add to reserved where on hand minus reserved is at least the quantity', plus a hold row with an expiry. The hold mechanics, the expiry job and the flash-sale buckets are the same as in the ticketing problem. This section covers what is special to checkout.

Choosing a warehouse. Rank the warehouses by distance to the customer and pick the nearest one that holds every line. If none does, allow a split into several shipments and tell the shopper. Choose first, then reserve against the choice. If that reserve fails, try the next warehouse once.

A split order has one group of holds per warehouse, all under the same order ID. A release or commit by order ID then covers every group. If any group cannot be held, the others are released, so the order is all or nothing.

Committing the hold. A hold lasts up to 15 minutes, but the parcel may ship hours or days later, and payment is captured only then. So once the card is authorized, the orchestrator sends 'commit the holds for order X', keyed by the order ID. Inventory runs one conditional update per hold: mark it committed and clear its expiry, only where it is still active. A committed hold still counts as reserved, so nobody else can buy that stock, and the expiry job skips it.

If a hold has already expired, the update changes no row and the commit fails. The orchestrator voids the authorization and fails the order. Without this step, every confirmed order would see its stock return to the shelf after 15 minutes. Shipping later turns each committed hold into a decrement of on hand, and a cancellation releases it.

Unknown results. If a reserve or commit call times out, the orchestrator does not know whether it happened. It retries with the same key. Inventory finds the existing hold and returns it, or creates one. It never guesses and never releases blind.

Reconciling. A nightly job compares each item's reserved count with the sum of its active and committed holds, and each committed hold with a live order. A hold whose order is failed, cancelled or missing is released and reported. A wrong count is rebuilt from the holds, which are the source of truth.