Inventory truth changes inside a transaction

The storefront displays one simple number, but carts, checkouts, staff adjustments, cancellations, and returns can change it concurrently. If two orders read the last unit and decrement outside a database lock, both can succeed and produce negative stock. Prevention starts with an atomic reservation or decrement inside a transaction, followed by a quantity check after the row is locked.

Separate availability display from the final decision

Showing In stock on a product page helps the shopper but cannot guarantee quantity until checkout. Final placement reprices the cart, locks the product or variant, verifies quantity, and records movement. When price changed or stock ran out, the shopper receives a clear conflict and can return to the cart rather than creating an incomplete order.

Record every adjustment

Do not expose a stock number that changes without reason. Receiving, sale, cancellation, refusal, return, and correction movements keep before and after quantity, reason, actor, and time. The ledger explains the current number and surfaces repeated corrections that may indicate a process or training problem.

Handle cancellation and refusal idempotently

Cancellation before fulfillment returns reserved quantity once. A COD refusal after dispatch may return saleable stock, but it uses a distinct reason because refusal also affects customer risk and delivery cost. Replayed cancellation or refusal events must never add quantity twice.

Inspect before restocking

A return request is not a stock movement. Receive and inspect the item, then decide saleable restock, quarantine, damage, or write-off. Each return line retains requested quantity, maximum refund, condition, and final disposition. Only the inspection decision changes inventory and starts the appropriate refund, exchange, or replacement path.

Separate money from stock while sharing a reference

A refund may settle tomorrow while inventory returns today, or the reverse. Use two explicit records tied to the return: stock movement and refund ledger. The refund has amount, currency snapshot, original rail, execution mode, reference, status, and diagnosable failure. Never rewrite the historical order total; append the movement that explains what happened.

Monitor low stock as a queue

A low-stock threshold is a triage tool, not a purchasing rule. Surface products and variants below the threshold with search and filters, then provide an audited adjustment. Large catalogs should export or process in bounded background jobs instead of holding the browser or worker in one unbounded request.

Essential tests

• Two concurrent orders for the final unit; only one succeeds.
• Replayed cancellation and refusal never restock twice.
• A return request does not change stock before inspection.
• Restock, quarantine, damage, and write-off create distinct movements.
• Partial refunds never exceed the refundable balance.
• Another tenant cannot read the product, movement, return, or refund.
• Reports exclude test orders and use the tenant timezone.

When every movement is atomic and recorded, inventory becomes trustworthy and aftercare becomes a logical extension of the original order instead of a series of unexplained manual edits.