PRD: Stock Reservation & Oversell Guard

Module	Inventory	PRD ID	PRD-RSV-001
Status	No item	FEAT	RSV
Epic	—	Plane	—
Date	2026-07-13	Version	v1.0
Packages	@nx/inventory	URD	RSV
Surface	BackendClient · Owner/Mgr
Owner	Phát Nguyễn

What a reservation is

A merchant can hold goods in several inventory locations, and each item at each location carries four stock numbers.

A reservation is a promise to set aside N units of an item for a specific holder: a sale order, a stock transfer ticket, or a production order. The goods are still on the shelf, but nobody else can sell them. The moment a cashier taps an item into an order on the POS, the system holds the matching stock.

The four stock numbers

Quoted from Stock Locations & Levels so nobody has to open another PRD. Each item at each location carries four numbers:

Number	Meaning
On-hand	The goods physically in the warehouse
Reserved	Already promised to another document, no longer sellable to anyone else
Available	The part that can still be sold
Incoming	Already left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On-hand - Reserved

Why overselling is the most expensive mistake

Overselling means promising the same item to two customers. The second one pays, then finds out it is gone, and the merchant has to apologise and refund. It happens because the system looks at a single "how much stock is left" number instead of "how much can still be sold".

Reservation closes that gap. Stock is held the instant an item lands on the order, not at payment, so two cashiers on two POS terminals cannot both sell the last can of soda. The same mechanism serves stock transfers (goods already promised to another location) and production orders (materials already promised to a batch).

The second half is traceability. One aggregate number, "3 reserved", says nothing about who is holding the stock or where to unstick it, so the owner sees stock stuck and cannot act on it. That is why every reservation carries the name of its holder.

The last can of soda, from cart to payment

Coke at the bar counter: on-hand 10, nothing reserved. Two POS terminals sell at once.

What happens	On-hand	Reserved	Available
POS 1 taps 3 cans into order #123	10	3	7
POS 2 taps 8 cans into order #124	10	3	7
POS 2 taps 7 cans into order #124 instead	10	10	0
The customer on order #123 drops 1 can	10	9	1
Order #123 is paid, 2 cans leave the shelf	8	7	1

• POS 2's request for 8 cans is refused right in the cart: available was only 7 at that moment. The customer has not paid, and the cashier can still offer something else.
• A reservation does not move on-hand. On-hand only drops when the order completes and the goods really leave the shelf.
• Open Coke's reservation detail at this point: order #124 is holding 7 cans. Wherever stock is stuck, that is where it can be unstuck.

The easiest thing to get wrong

Inventory never releases stock on a timer

There is no countdown and no time-based expiry: an order left open overnight still holds its stock.

Inventory does not know whether that order is alive or dead. An order left open for 2 hours might be a table halfway through a meal. Only whoever created the reservation knows, so that is who commands the release: a sale order when it is voided or completed, a stock transfer when goods leave the source location, a production order when the batch finishes or is cancelled.

The release happens quietly, with no notification. If an abandoned order is holding stock, the owner finds it on the reservation detail screen and voids it.

1. Goals & Non-Goals

Goals

• Reserve stock at the moment an item is tapped into the order, not at payment, so an out-of-stock refusal always lands while things can still be fixed.
• Make the oversell guard the default rule for every item; allow oversell is the exception an owner deliberately turns on per item.
• Tie every reservation to a specific holder (sale order, stock transfer, production order) so the reserved amount is always traceable back to its source.
• Let the owner see who is holding how much, with the lines adding up exactly to the reserved total.
• Put the release decision with whoever created the reservation, not with inventory, and drop any time-based expiry.

Non-Goals

• Consuming real stock when an order completes - owned by the Inventory ledger feature and the Stock items & levels feature.
• The lifecycle of sale orders, stock transfers and production orders - inventory only takes reserve and release commands, it does not decide when.
• The incoming number for goods in transit and the three transfer states - owned by the Stock transfer feature.
• Inventory valuation of reserved stock - reservation touches quantities only, never money.
• Publishing the available number to e-commerce marketplaces - owned by the Omnichannel sync feature.

2. Success Metrics

Metric	Target / signal
Unintended overselling	Down to 0 for items without allow oversell; every remaining negative sale is on an item whose flag is on
Out-of-stock detection latency	The out-of-stock message shows up in the cart, never after the customer has paid
Reserved-number integrity	The reservation records always add up exactly to the reserved number on the stock table
Stuck stock	The count of items whose reserved amount cannot be traced to a live order or ticket trends to 0
Merchant self-service	Owners find the source of a reservation from the detail screen, without asking the operations team

3. Personas & Scenarios

Persona	Goal in this feature
Cashier	Tap an item into the order and know immediately whether it is in stock, before the customer pays
Merchant owner / Manager	Turn on allow oversell for the right items, and trace who is holding stock when available looks unusually low
Inventory manager	Know which stock is committed to a transfer and which is committed to sale orders
System	Take reserve commands, take release commands, and guarantee available always equals on-hand minus reserved

Core scenario: the cashier taps 3 cans into an order on the POS → the system checks available, reserves 3 cans and stamps that order onto the reservation record → available drops by 3 on every other POS terminal at once → the customer changes their mind and drops 1 can → that order's reservation falls to 2, available climbs back by 1, and no notification pops up → the customer pays, the order completes, and the reservation turns into a real stock deduction.

4. User Stories

#	As a	I want	So that
01	cashier	the system to tell me an item is out of stock the moment I tap it into the order	I can offer the customer something else before they pay
02	cashier	the stock in my cart to be safe from another POS terminal selling it out from under me	my order always makes it to completion
03	merchant owner	allow oversell on for ice cubes and straws but still blocked for chicken and milk	a few hard-to-count items do not freeze the whole counter
04	merchant owner	to open an item's detail and see which order and which ticket is holding how much	I can unstick stock at the right place
05	inventory manager	goods on a stock transfer held at the source location	nobody sells stock already promised to another location
06	inventory manager	inventory never to release stock on a timer	an order waiting on a customer's decision does not lose its stock halfway through

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Tapping an item into an order on the POS reserves the matching stock right away, without waiting for payment. • On-hand does not move, the goods are still on the shelf. • Reserved goes up by exactly the quantity tapped and available goes down by exactly the same amount, at the same time. • Changing the quantity on an order line adjusts that order's reservation to match, up or down by exactly the difference.	✅	URD-RSV-001
FR-002	The system refuses any reservation beyond available, by default for every item. • Available is 2 and the cashier taps 3: the request is refused right in the cart, with an out-of-stock message. • The refusal happens before the customer pays, and no line is added to the order. • Two POS terminals tapping the last can at the same instant: exactly one wins the reservation, the other is refused.	✅	URD-RSV-002
FR-003	Every item carries an "Allow oversell" flag, off by default. • Flag on: the item can be reserved and sold past its stock, and available goes negative without an error. • Flag off: the item follows the guard rule in FR-002. • The flag is set per item per inventory location, so the same item can be guarded at one location and allowed to go negative at another.	✅	URD-RSV-003
FR-004	Every reservation is a record with a named holder, not a shared number. • The holder is one of three kinds: a sale order, a stock transfer, or a production order. • The record captures the holder kind, the holder's identifier, the item, the inventory location and the quantity reserved. • Two different orders reserving the same item produce two separate records; they are never merged into one.	🚧	URD-RSV-004
FR-005	The reserved number on the stock table is nothing more than the sum of the reservation records. • Adding or removing a reservation record moves the total immediately. • The reservation records for one item at one location always add up exactly to the reserved number on display. • Available always equals on-hand minus reserved, at every point it can be read.	🚧	URD-RSV-004 · URD-RSV-005
FR-006	An item's reservation detail screen expands into the individual holders. • Each line shows: holder kind (sale order / stock transfer / production order), the holder's identifier, the inventory location, the quantity reserved, and when it was reserved. • The holder identifier is clickable and opens the order or ticket directly. • The lines add up exactly to the reserved number on the stock table.	🚧	URD-RSV-005
FR-007	Removing a line from an order or voiding the whole order releases that order's reserved stock immediately. • Reserved drops by exactly that order's share, and available climbs back by exactly the same amount. • The cashier does nothing extra, and no notification pops up. • Other orders' reservations on the same item are left untouched.	✅	URD-RSV-006
FR-008	Inventory does not decide on its own when to release reserved stock. • No countdown, no time-based expiry: an order left open overnight still holds its stock. • The release is always commanded by whoever created the reservation, on that holder's own lifecycle: a sale order when it is voided or completed, a stock transfer when goods leave the source location, a production order when the batch finishes or is cancelled.	✅	URD-RSV-007
FR-009	Prepared items and bundles go through the same reservation mechanism at the moment they are tapped into the order. • Tapping an item with a bill of materials explodes it into its individual materials and reserves each of them; the parent item itself is not reserved. • If one material or one component is short, the system reports the item as sold out right in the cart, unless that component has allow oversell on. • The available number for an item with a bill of materials is the smallest number of batches its materials can still make; once that number hits 0, the menu shows "sold out". • Dropping the item from the order releases all of its reserved materials at once.	🔶	URD-RSV-008
FR-010	Goods on a stock transfer are held at the source location, from the moment the ticket is raised until the goods leave that location. • Raising a transfer creates a reservation record in the ticket's name at the source location: available at the source drops immediately, on-hand has not moved yet. • When the goods leave the source, the reservation is released and on-hand at the source drops at the same time, so available at the source does not move a second time. • From the moment goods leave the source until the destination confirms receipt, the stock sits in the destination's incoming number (owned by the Stock transfer feature), and the source location remains accountable for it. • Voiding a transfer before the goods leave releases the reservation back to the source location immediately.	🚧	URD-RSV-009
FR-011	Every oversell event is written to a log for reconciliation. • Each out-of-stock refusal records the item, the inventory location, the quantity requested and the available number at that moment. • Each successful negative sale allowed by the allow-oversell flag is logged too, as a deliberate oversell. • The owner filters by item to see which items keep getting refused or keep going negative, as the basis for reordering or for turning the flag on.	🚧	URD-RSV-010

5.1 Acceptance criteria

• An item has on-hand 10, reserved 0, available 10 → the cashier taps 3 into an order on the POS → the stock table shows on-hand 10, reserved 3, available 7.
• An item has available 2 and allow oversell off → the cashier taps 3 into the cart → the system refuses right in the cart with an out-of-stock message, and no line is added to the order.
• Two POS terminals tap the last can into two different orders at the same instant → one wins the reservation, the other gets the out-of-stock message.
• Turn on "Allow oversell" for ice cubes, currently at available 0 → the cashier taps 5 more ice into the cart → the system reserves them, reserved goes up by 5, available goes to -5, and no error is raised.
• Order #123 reserves 2 cans and order #124 reserves 1 can of the same item → exactly two separate reservation records exist, never merged into one, and the item's reserved total is 3.
• Order #123 reserves 2 cans and transfer #45 reserves 1 can of the same item → open that item's reservation detail → exactly two lines show up: sale order #123 holding 2, stock transfer #45 holding 1, adding up to the reserved total of 3.
• On the reservation detail screen, click the identifier of order #123 → sale order #123 opens directly.
• An order reserves 3 units → the cashier deletes a line worth 1 unit → reserved falls to 1, available climbs back by 2, and no notification appears.
• An order reserves 3 units → the customer voids the order → reserved drops by 3 immediately, available climbs back by 3, and other orders' reservations on the same item do not move.
• Leave an order with reserved stock open for 24 hours, untouched → the stock is still held for that order, with no automatic release having happened.
• The milk tea bill of materials needs 50ml of milk; stock has 60ml of milk → tap 1 milk tea into the order → 50ml of milk is reserved, milk's available falls to 10ml → tap another milk tea → the system reports the item as sold out right in the cart.
• The tapioca pearl material has allow oversell on and available 0 → tap an item containing tapioca pearls into the order → the item still goes in, and pearls' available goes negative.
• Drop the milk tea from the order → all 50ml of milk and the item's other materials are released at once, and each material's available climbs back by exactly what was reserved.
• Raise a transfer of 5 units from the main warehouse to the bar counter → at the warehouse, on-hand does not move, reserved goes up by 5, available drops by 5; at the bar counter, nothing has moved yet.
• Void that transfer before the goods leave the warehouse → reserved at the warehouse drops by 5 and available climbs back by 5.
• A cashier is refused for lack of stock 3 times in one day on the same item → the owner filters on that item → all 3 refusals show up, each with the quantity requested and the available number at that moment.
• Ice cubes have allow oversell on and available 0 → the cashier taps 5 more into the cart → the reservation succeeds and a deliberate-oversell line is logged at the same time; filtering the log by ice cubes shows exactly that line.

6. Non-Functional Requirements

Aspect	Requirement
Data integrity	The database itself enforces available equals on-hand minus reserved; it does not rely on caller discipline. Any write that breaks the equation is rejected at the storage layer
Concurrency	The availability check and the reservation write happen in one atomic write, so two simultaneous reservations on the same item cannot both succeed when there is only enough stock for one
Idempotency	The same reserve or release command sent twice for the same holder takes effect once; the reserved number is never double-counted or double-decremented
No line cap	However many lines a sale order has, every one of them is reserved and released; there is no hidden cut-off
Performance	Reserving stock for a multi-line order completes in a single call when the cashier taps an item; it does not slow down work at the counter
Merchant scoping	Reservation records and the stock table are confined to the user's own merchant
i18n	Holder-kind labels and out-of-stock messages are bilingual

7. UX & Flows

The stock management screen in the Client app shows four numbers per item per inventory location. The reserved number is clickable and opens the reservation detail screen, which lists every holder. The "Allow oversell" flag sits in the item's stock edit form, next to the low-stock threshold. On the POS the reservation flow runs in the background; the cashier only sees it when a request is refused for lack of stock.

8. Data & Domain

Concept	Role
Reservation record	A promise to set aside N units of an item at one location for a specific holder
Holder	Whoever created the reservation: a sale order, a stock transfer, or a production order. Recorded as a kind + identifier pair
Reserved	The total quantity of all reservation records on one item at one location
Available	On-hand minus reserved. The number that decides whether a reservation succeeds or is refused
Allow oversell	A per-item, per-location flag that lets available go negative. Off by default
Oversell event	A record of a reservation blocked for lack of stock, or of a deliberate negative sale

Conceptual level only - the full schema and invariants live in the inventory domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	STK Stock items & levels	the four numbers per item per location are where reservation writes land.
02	Sale	the sale order commands a reserve when an item is tapped, and a release when a line is deleted, an order is voided, or an order completes.
03	TRF Stock transfers	the transfer ticket commands a reserve at the source location and a release when the goods leave.
04	MFG Production orders	the production order commands a reserve on the materials for a batch.
05	BOM Bill of materials	the explosion decides which materials get reserved, and how much, for a prepared item.

Assumptions

#	Assumption	What breaks if it is wrong
01	Every sale order is tied to a definite inventory location, so a reservation always knows which location it comes out of.	An order with no location has nowhere to hold stock; the system either blocks the order or reserves at the wrong location and corrupts availability in both places.
02	Whoever created a reservation always commands the release when its lifecycle ends; inventory never guesses on its behalf.	A dead order that never commands a release holds its stock indefinitely, availability reads artificially low, and the owner has to hunt the order down and void it by hand.
03	Items that are not stock-tracked reserve nothing and are never refused for lack of stock.	Guarding an item that is not stock-tracked is a false refusal: it has no available number to compare against, and the counter freezes on an item permanently shown as sold out.
04	Turning on allow oversell for an item is a conscious owner decision, accepting that available may go negative.	A flag turned on by mistake, or turned on for every item, disables the oversell guard entirely, and overselling comes back exactly as it was before this feature.

10. Release Plan & Criteria

Aspect	Plan
Phase	P2 (Inventory) - see the URD feature catalogue
Rollout	All merchants; no feature flag. Allow oversell defaults to off for every existing item
Migration	Today's reserved numbers are converted into reservation records under their matching holders; any reserved amount that cannot be traced to a live order or ticket is zeroed out and written to a reconciliation line
Release criteria	No overselling left on items without allow oversell; the reservation records match the reserved number across the whole sample dataset; the reservation detail screen expands into the correct holders
Monitoring	Out-of-stock refusals per item, count of items with negative available, count of reservation records with no live holder

References

• URD: Stock reservation & oversell guard
• Related: Stock items & levels · Stock transfers · Bill of materials · Production orders · Inventory ledger
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & Open Questions

#	Risk / question	Mitigation / status
01	An order is forgotten and holds stock indefinitely, because inventory has no expiry mechanism	Accepted deliberately (FR-008); the reservation detail screen lets the owner find the stuck order and void it (FR-006)
02	Allow oversell on an item sends available deep into negative with nobody noticing	Every negative sale is logged and filterable by item (FR-011)
03	Materials get reserved at one explosion depth and consumed at another, so what was reserved and what was deducted drift apart	The explosion at reserve time and at consume time runs through the same calculation and stops at the same level (FR-009)
04	The same reserve command is resent on a flaky network and double-counts the reserved number	Reserve and release commands are idempotent per holder (§6)
05	The allow-oversell flag is per item per location, and a multi-location owner may turn it on at one location and forget the others	Open: consider a merchant-level default for the flag, overridable per location

Frequently asked questions

#	Question	Answer
01	Why reserve stock at tap time instead of waiting for payment?	Because tap time is when things can still be fixed. If we only discover the item is gone once the customer has paid, the merchant has to refund and apologise. Reserve first, deduct later: the deduction step when an order completes never fails for lack of stock, because the stock was already held from the start.
02	When should allow oversell be used?	When an item is hard to count exactly and blocking the sale would freeze the counter: ice cubes, straws, napkins. A cafe turns the flag on for those and keeps the guard on for chicken, milk and beer - the things that are genuinely short when they run short.
03	Why doesn't inventory release stock after a while?	Because inventory does not know whether the order is alive or dead. An order left open for 2 hours might be a table halfway through a meal, or it might be an abandoned order. Only sale knows, so the sale order commands the release. If inventory ran its own countdown, it would release the stock of a table that is still eating.
04	Reserved says 3 cans but I have no idea who is holding them - now what?	Open that item's reservation detail screen. It expands line by line: which order is holding how much, which stock transfer is holding how much, and each one is clickable straight through to the order or ticket to deal with it.
05	For a prepared item, do we reserve the item or the materials?	The materials. Tapping one milk tea makes the system explode the bill of materials into milk, tea and pearls, then reserve each of them. So two orders both asking for milk tea compete over the actual milk left, and when the milk runs out the counter sees "sold out" immediately.
06	Can stock on a transfer ticket still be sold at the source location?	No. That stock is already committed to another location, so it is held at the source and available drops the moment the ticket is raised. The source location stays accountable for it until the destination confirms receipt.