Reservation Ledger

The naive model for stock is a counter that goes up and down. It is compact, it is wrong in three ways, and the wrongness only appears at scale.

The ledger model records events — reserved, released, allocated, adjusted — and derives the available quantity as total minus outstanding reservations. The count becomes a projection rather than the truth.

Why it matters

• A counter has no history. When the recorded stock disagrees with what is physically on the shelf, a counter tells you nothing about how it got there. A ledger tells you exactly which reservation was never released.
• A single mutable count conflates three facts — how much exists, how much is committed, how much can be sold — so every concurrent update to any of them is a conflict on the same field.
• Reconciliation against the physical world is possible only with a ledger, and in any business touching physical goods, reconciliation is not optional.

Implementation patterns

• Separate total, reserved and available, with available derived. A seller's stock update and a customer's reservation then touch different fields and most contention disappears.
• Reserve with a conditional write — succeed only if available is greater than zero — as one atomic operation on one row. Optimistic concurrency at the storage layer, needing no lock manager.
• Time-bound every reservation, with expiry enforced server-side. An abandoned client cannot release its own hold, so a sweeper or a store-level TTL must.
• Make reserve, release and allocate all idempotent, because each will be retried.
• Reserve before payment authorisation, not after. This is the sequencing decision that allows substitution, partial fulfilment or re-pricing instead of a generic error at the payment step — cheap to decide now, expensive to change later.
• Hold safety stock, selling less than the claimed count, which converts an unpredictable physical failure into a predictable cost.

Industry example

Quick-commerce platforms such as Zepto need this per dark store: browse availability can be a stale cached projection, but the reservation against a specific store's shelf must be exact, single-writer and transactional. The expensive guarantee is needed only on the cheapest path — checkout volume is a small fraction of browse volume — so the strongly consistent component stays small and independently protectable.

Fashion marketplaces such as Myntra face the same structure with a third writer: the seller, who can reduce stock mid-checkout. In the ledger model a seller reduction lowers available and cannot invalidate existing reservations; going below what is already reserved is an explicit business exception rather than a silent overwrite.

Failure scenarios

• A counter decremented without a record, leaving discrepancies with no explanation.
• Reservations that leak because expiry was client-enforced or the sweeper failed silently, quietly reducing sellable stock.
• Reserving after payment, which makes every stock failure a payment-time error with no graceful path.
• Non-idempotent release, double-releasing stock and permitting an oversell.
• No physical reconciliation, so drift accumulates invisibly until a fulfilment centre disputes the numbers.

Trade-offs

A ledger is more storage, more write volume and a derived read that must be maintained — typically a cached available count updated from the ledger, which reintroduces a projection to keep correct.

The alternative is simpler and provides no audit trail, no reconciliation path and no explanation when the numbers are wrong. In any business where stock corresponds to physical objects, the audit trail is worth more than the simplicity, because the divergence is guaranteed and the question "why" will be asked.

Interview question

"Your available count says three and the shelf has one. Walk me through how you would find out what happened, and tell me what your data model needs to make that possible."