PRD: Lots, Expiry & Picking Strategy

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

What a lot is

A lot is one batch of goods received together, sharing one lot code and one expiry date. Ten cartons of milk received this morning expiring 2026-08-01 are one lot; ten cartons received next week with a different expiry are another lot.

A merchant turns lot tracking on per item, right inside the item edit form. The flag is off by default. Turn it on and that item's stock at each inventory location is split out by lot. Several merchants sit under one organizer, and each merchant decides for itself which items need lots.

The four numbers in stock

Lifted from Stock locations & levels so there is no need to open another PRD. Every item at every location carries four numbers:

Number	What the system calls it	Meaning
On-hand	on-hand	Goods physically sitting in the location
Reserved	reserved	Already promised to another document, no longer sellable to anyone else
Available	available	The part still sellable
Incoming	incoming	Left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On-hand - Reserved

Turn lots on and these four numbers drop one level further down: every lot carries its own four numbers, and the item's stock at a location is the sum of the lots there.

Why a single stock number is not enough

The same SKU does not mean interchangeable units. A crate of milk received today and one received last week expire on different days. If the system keeps a single stock number for "fresh milk", nobody knows which part is about to expire, and staff grab whatever crate is nearest. The old milk sits there until it has to be thrown out.

Only with lots can the system answer the two questions F&B and fresh-goods retail ask every day: what is about to expire, and which goods go out first when we sell.

One lot-tracked item, end to end

Fresh milk, on the earliest expiry first (FEFO) strategy. Receive two lots, then sell 4 cartons. The cashier picks no lot.

What happens	Lot A · expires 08-01 · received 07-01	Lot B · expires 07-20 · received 07-05	Total stock
Receive lot A: 5 cartons	5	0	5
Receive lot B: 3 cartons	5	3	8
Sell 4 cartons	4	0	4

• Lot B expires sooner, so it is drawn down first: all 3 cartons. The remaining 1 carton spills over into lot A.
• One sale touches two lots, and the inventory ledger writes two lines: minus 3 from lot B, minus 1 from lot A.
• Switch this item to the first in, first out (FIFO) strategy and lot A is drawn down first, because lot A entered stock on 07-01, earlier than lot B.
• A few days later lot A crosses the alert threshold (7 days by default) and appears on the near-expiry lot list.

The easiest thing to get wrong

The picking strategy is not a valuation method

FIFO here is a lot pick order: which lot leaves the shelf first. It says nothing about the money attached to that carton of milk.

Inventory valuation is a separate config, set on the Inventory Valuation screen, and it has only two options: weighted moving average or standard cost. Changing the picking strategy does not move the valuation, and changing the valuation method does not reorder lot picking.

When two lots tie, the system evaluates each key in turn until the tie is broken, so the result is always explainable and repeatable. A lot with no expiry always sorts after lots that have one.

1. Goals & Non-goals

Goals

• Turn lot tracking on or off per item, off by default. Items without lots behave exactly as they do today.
• Split an item's stock into several lots, each with its own lot code, received date, expiry date and remaining quantity.
• Let the owner choose a picking strategy per item: earliest expiry first, or first in, first out.
• Auto-pick lots when selling or issuing stock, spilling across several lots when one is not enough, and never forcing the seller to pick a lot by hand.
• Apply a fixed, explainable tie-break order when several lots rank equally.
• Flag near-expiry lots against a merchant-defined day threshold, defaulting to 7 days.
• Reserve the per-unit serial lifecycle up front, so the feature can be opened later without a rewrite.

Non-goals

• Per-unit serials: the model and its states are defined in this document, but the merchant-facing operations are out of scope for this increment.
• Inventory valuation methods (weighted moving average, standard cost), which belong to Inventory valuation.
• Writing off expired goods and booking the matching shrinkage, which belongs to Inventory tickets.
• Tracing a lot back to every customer who bought from it (recall).
• Lot-level expiry control for consignment goods.

2. Success metrics

Metric	Target / signal
Expired goods thrown out	Trends down at F&B merchants after lots are enabled, measured by expiry-reason shrinkage quantity on the inventory ledger
Lot-picking correctness	The lot deducted on a sale is always the one the configured strategy points at; never an arbitrary pick
Near-expiry alert usage	The number of merchants opening the near-expiry lot list each week trends up
Added operational cost	Enabling lots does not slow the counter down; cashiers still never pick a lot

3. Personas & scenarios

Persona	Goal in this feature
Owner / Manager	Enable lots on items with a shelf life, choose a picking strategy, see which lots are about to expire and act early
Warehouse staff	Fill in lot code and expiry on receipt, read stock per lot to know which goods to pull first
Cashier	Sell as usual, without thinking about lots at all
System	Pick the right lot per strategy when stock is deducted, and raise a flag before goods expire

Core scenario: the owner enables lot tracking on "Fresh milk" and picks earliest expiry first → warehouse staff receive two milk deliveries with two lot codes and two different expiry dates → the stock screen shows two separate lots → a cashier sells 4 cartons without picking a lot → the system drains the lot expiring soonest, then spills into the other one → a few days later the remaining lot crosses the alert threshold and shows up on the near-expiry list for the owner to deal with.

4. User stories

#	As a	I want	So that
01	owner	to enable lot tracking only on items with a shelf life	my other items are not burdened with data nobody needs
02	warehouse staff	to fill in lot code and expiry right at receiving	I know later exactly what expires when
03	warehouse staff	to see an item's stock split by lot	I pull the lot I am supposed to pull
04	owner	earliest expiry first on fresh goods and first in, first out on dry goods	each kind of item behaves the way it should
05	owner	to change the picking strategy without inventory valuation moving with it	the two decisions stay independent
06	cashier	to sell without picking a lot	I am not slowed down at the counter
07	owner	a near-expiry lot list based on a day threshold I set	I discount the goods or return them to the vendor in time

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	Every item carries two independent tracking flags in the item edit form: lot tracking and serial tracking. • Both are off by default. An item with neither flag on keeps a single stock number per location, exactly as today. • Lot tracking requires a lot code at receiving; items with a shelf life also get an expiry date. • The two flags are independent. Turning one on never turns the other on.	🚧	URD-LSE-001
FR-002	When goods arrive for a lot-tracked item, each received line is booked into a lot, identified by its lot code. • The receiver fills in lot code, expiry date and manufacturing date (optional) on the receiving line. • That whole line holds many units, but they all share one lot code and one expiry. • A lot code not yet present at the receiving location creates a new lot. Receiving the same code again at the same location rolls the quantity into the existing lot instead of creating a second one. • A lot's received date is the moment the receiving ticket completes. A lot that is topped up keeps its original received date.	🚧	URD-LSE-002
FR-003	Stock for a lot-tracked item is split per lot at each location. • Every lot holds four stock figures of its own: on-hand, reserved, available, incoming. • The item's stock at a location is the sum of its lots at that location. • A lot drained to zero stays in history; it simply stops being eligible for picking.	🚧	URD-LSE-002 · URD-LSE-008
FR-004	Every lot-tracked item is assigned one picking strategy, set in the item edit form. • Earliest expiry first (FEFO): draw down the lot closest to expiry first. • First in, first out (FIFO): draw down the lot that entered stock earliest, rotating strictly in receiving order.	🚧	URD-LSE-004
FR-005	The picking strategy and the inventory valuation method are two independent configs. • Changing the picking strategy does not move the item's inventory valuation. • Changing the valuation method does not reorder lot picking.	🚧	URD-LSE-005
FR-006	Lot pick order is fixed by the configured strategy, evaluating each key in turn until the tie is broken. • Earliest expiry first (FEFO): earliest expiry → earliest received date → lot code in ascending alphabetical order. • First in, first out (FIFO): earliest received date → earliest expiry → lot code in ascending alphabetical order. • On the expiry key, a lot with no expiry always sorts after lots that have one.	🚧	URD-LSE-006
FR-007	On a sale or a stock issue, the system picks the lot. The seller never picks by hand. • It draws down lot by lot in the configured strategy's order, draining the first lot before spilling into the next, until the quantity is covered. • One issue can touch several lots, and the inventory ledger writes one line per lot deducted. • Reserving stock for an order reserves it on the exact lots that will be deducted, so two concurrent orders never fight over the same lot.	🚧	URD-LSE-007
FR-008	Users see an item's per-lot stock breakdown right on the stock screen. • Each lot row shows: lot code, location, remaining quantity, received date, expiry date. • The list comes pre-sorted in the exact order the lots will be picked, so the top row is the lot to be deducted next. • An expired lot is clearly marked on its row.	🚧	URD-LSE-008
FR-009	The merchant sets the near-expiry day threshold in inventory settings. • Defaults to 7 days until the merchant changes it. • One number applies to the whole merchant; it is not set per item. • Changing the number takes effect on the very next view of the list, with no wait until the following day.	🚧	URD-LSE-009
FR-010	The Client app carries a near-expiry lot list so the owner can act early. • The list covers every lot that still has stock and whose expiry falls inside the configured day threshold, counted from today. • Already-expired lots are on this list too, sorted to the very top. • Each row shows the item, lot code, location, remaining quantity and days left until expiry.	🚧	URD-LSE-009
FR-011	Serial-tracked items carry an identifier per unit, and each unit moves through a lifecycle of its own. • A serial belongs to exactly one unit and is never reused for another. • Unit states: in stock → sold, plus later states such as returned or lost. • A sold unit is linked to the order that sold it, so a serial traces back to the customer.	🚧	URD-LSE-003
FR-012	An item can have both lot and serial tracking on. Each unit then carries its own serial while also belonging to a lot with a shared expiry.	🚧	URD-LSE-001 · URD-LSE-003

5.1 Acceptance criteria

• Open the edit form of a freshly created item → both the lot tracking and serial tracking flags are off.
• Enable lot tracking on "Fresh milk", then receive 10 cartons with lot code L1 and expiry 2026-07-20 → the stock screen shows one L1 lot row with 10 cartons, received today, expiring 2026-07-20.
• Receive another 10 cartons under lot code L1 at the same location → still one L1 row, quantity now 20 cartons, no second lot row appears.
• Receive 5 more cartons under lot code L2 with expiry 2026-08-01 → the stock screen shows two lot rows, and the item's total stock is 25 cartons.
• The item is on earliest expiry first, with lot A (5 units, expiry 2026-08-01, received 2026-07-01) and lot B (3 units, expiry 2026-07-20, received 2026-07-05) → sell 4 units → lot B is drained of all 3 units and lot A is deducted 1 unit, leaving 4 units, all of them in lot A.
• Same sale → open the inventory ledger → two lines appear, one deducting 3 units from lot B and one deducting 1 unit from lot A.
• Lot C (expiry 2026-08-01, received 2026-07-01) and lot D (expiry 2026-08-01, received 2026-07-03) exist → sell 1 unit → lot C is deducted, because on an equal expiry the lot received first wins.
• Lot E and lot F share an expiry and a received date, with lot codes "E" and "F" → sell 1 unit → lot E is deducted, because "E" sorts before "F".
• The item is on first in, first out, with lot A (expiry 2026-07-20, received 2026-07-05) and lot B (expiry 2026-08-01, received 2026-07-01) → sell 1 unit → lot B is deducted because it entered stock first, even though lot A expires sooner.
• Sell lot L1 down to nothing → the stock screen still shows the L1 row at quantity 0, and the next sale skips L1 and moves to the following lot.
• A lot expired yesterday still has stock → open the item's stock screen → its row carries the expired marker.
• Switch an item's picking strategy from earliest expiry first to first in, first out → the item's inventory valuation stays at exactly the same number.
• Switch an item's valuation method → the lot order on the stock screen is unchanged, and the lot to be deducted next is still the same one.
• A cashier sells a multi-lot item at the POS → the sale screen never asks for a lot, and the order completes normally.
• Add 2 units of an item to the cart when the soonest-expiring lot has exactly 2 units left → open the stock screen → that lot shows 2 reserved and 0 available, and no other lot is touched.
• The merchant has never opened the near-expiry settings, and a lot is 6 days from expiry → open the near-expiry lot list → the lot is there, because the default threshold is 7 days.
• Change the threshold to 3 days and reopen the list → the lot 6 days from expiry drops off the list.
• A lot expired yesterday → open the near-expiry lot list → it sits at the top of the list, marked as expired.
• Enable serial tracking on an item, then receive 1 unit with a specific IMEI → that unit is in stock; sell it → it moves to sold and traces back to the order that sold it.
• Enable both lot and serial tracking on an item, then receive 3 units under lot code L1 with expiry 2026-08-01 and 3 different serials → the stock screen shows lot L1 with 3 units, and each unit resolves to its own serial; sell 1 unit → lot L1 is left with 2 units and the sold unit moves to sold.

6. Non-functional requirements

Aspect	Requirement
Data integrity	A lot code is unique within one item of one merchant; a serial is unique within one merchant
Concurrency	Two simultaneous sales on the same lot must never drive that lot's stock below 0; reservation locks per lot row
Backward compatibility	Items without lot tracking behave exactly as today: one stock row per item-and-location pair
Performance	A sale touching several lots is still handled in a single write, not split into several calls from the POS
Traceability	Every inventory ledger line records the lot code, expiry and serial (where present) as of the moment it happened, and never changes afterwards, even if the lot is edited
Merchant scoping	Lots, serials and the near-expiry setting are all confined to the user's own merchant
i18n	Lot state and serial state labels are bilingual

7. UX & flows

8. Data & domain

Concept	Role
Lot	One batch received together, carrying a lot code and an expiry shared by many units
Lot stock record	A lot's four stock figures at one location: on-hand, reserved, available, incoming
Expiry	A lot's expiry date; a lot with no expiry is still valid and sorts after lots that have one when picking
Manufacturing date	Optional information captured with a lot, used to reconcile quality disputes
Lot tracking flag	Per-item flag, off by default, deciding whether stock is split by lot
Serial tracking flag	Per-item flag, off by default, deciding whether each unit is individually identified
Picking strategy	Per-item config: earliest expiry first (FEFO) or first in, first out (FIFO)
Serialized unit	A single unit carrying its own identifier, moving through a lifecycle: in stock, sold, and later states
Near-expiry threshold	A day count set by the merchant, defaulting to 7, deciding which lots count as near-expiry

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

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	STK Stock items & levels	a lot is a subdivision inside a stock record, so the four stock figures must work first.
02	RSV Reservations	reserving stock for an order has to hold the exact lot, not just the item.
03	TKT Inventory tickets	a lot is born when a receiving ticket completes, so the lot code and expiry fields live on the ticket line.
04	LDG Inventory ledger	every lot deduction writes a ledger line carrying the lot code and expiry.
05	MAT Materials and the product catalog	the lot and serial flags are set on the item, whether that item is a material or a product variant.

Assumptions

#	Assumption	What breaks if it is wrong
01	Most merchants only enable lots on a small group of items (fresh goods, goods with a shelf life) and leave the rest lot-free.	A merchant enabling lots across the whole catalog slows receiving right down, because every line needs a lot code, and the number of stock rows swells with the number of lots.
02	Whoever receives the goods already has the lot code printed on the packaging or on the vendor's paperwork, and can enter it on the spot.	If the vendor prints no lot code, staff invent one, and an invented code cannot be reconciled back against the vendor's paperwork in a quality dispute.
03	Merchants are fine with a single near-expiry threshold for the whole catalog and do not yet need a per-item one.	A merchant selling both fresh goods (3-day shelf life) and dry goods (12-month shelf life) finds a single threshold always wrong for one of them: either it warns too late, or the list fills with goods nobody needs to worry about.
04	The picking strategy has only two options; nobody needs to pick a lot manually at the counter yet.	If a real case demands a manual lot pick (a customer asks for a specific lot, a warranty claim), the cashier has no way to record the right lot, and the lot on the document diverges from the goods that left.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory) - see the URD feature catalog
Rollout	All merchants; the lot tracking flag is off by default, so existing merchants see no change until they turn it on themselves
Migration	Existing stock on every item is treated as lot-free; enabling lots on an item that already has stock parks the old stock in a lot with no code and no expiry, which is picked last per the order in FR-006
Release criteria	Receiving captures lots; the stock screen splits by lot; sales draw down the right lot under both strategies; tie-breaks resolve in the right order on a sample dataset; the near-expiry list matches the configured threshold
Monitoring	Merchants with lots enabled, expired lots still holding stock, issues touching several lots, mismatches between the lot the system picked and the lot staff actually pulled

References

• URD: Lots, Expiry & Picking Strategy
• Related: Stock items & levels · Reservations · Inventory Valuation · Inventory ledger · Inventory tickets
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Enabling lots slows receiving down, because each line now needs a lot code and an expiry	The lot tracking flag is off by default and set per item (FR-001), so the merchant only pays this cost on the goods that genuinely need it
02	An item with several lots, picked wrong, leaves the old goods sitting there until they expire	Lot pick order is fixed and explainable (FR-006), and the stock screen sorts lots in the exact picking order so the merchant can verify it themselves (FR-008)
03	Merchants confuse the picking strategy with the valuation method and assume changing one moves the other	The two configs are kept apart (FR-005), and each is set in its own place
04	An expired lot still has stock and still gets picked for a sale	Expired lots are marked on the stock screen and sorted to the top of the alert list (FR-008, FR-010); open: whether selling an expired lot is blocked outright or merely flagged, pending PO decision
05	A single merchant-wide threshold does not fit merchants selling both fresh and dry goods	Open: consider a per-category threshold if a real merchant asks for it
06	The serialized-unit lifecycle may not match what merchants selling IMEI goods actually need	The lifecycle only commits to the two certain states (in stock, sold) and leaves room for later states such as returned or lost (FR-011)
07	The default picking strategy is undecided for owners who enable lots without choosing one	Open: the PO decides the default (earliest expiry first or first in, first out) before release; FR-004 only defines the two options

FAQ

#	Question	Answer
01	I do not sell anything with a shelf life, do I have to enter lots?	No. The lot tracking flag is off by default, and while it is off everything works exactly as before: one stock number per item per location.
02	What is the difference between a lot and a serial?	A lot is a group of units received together, sharing a lot code and an expiry, a good fit for milk, meat, baked goods. A serial is a code for one single unit, such as the IMEI of an individual phone. The two flags are independent, and an item can have both on: each unit carries its own serial while also belonging to a lot with a shared expiry.
03	Does the picking strategy change inventory valuation?	No. The picking strategy only decides which lot goes out first. Inventory valuation is calculated its own way and does not move when you change the picking strategy.
04	Does the cashier have to pick a lot when selling?	No. The system draws down lots per the configured strategy. One sale can touch several lots if the first one does not cover the quantity.
05	Two lots expire on the same day, which one goes out?	Under earliest expiry first, the tie goes to the lot received earlier, and if the received dates match too, to the lot code in alphabetical order. Under first in, first out, the system looks at the received date first, and expiry is only the secondary key.
06	How far ahead of expiry does the system flag a lot?	7 days by default. The merchant changes that number in inventory settings, and it takes effect on the very next view.
07	What about a lot with no expiry?	Still perfectly valid. It is picked after every lot that has an expiry, and it never shows up on the near-expiry lot list.