PRD: Inventory Valuation

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

What inventory valuation is

Cost is what one unit of an item sitting in a location is worth. On a sale, the selling price minus the cost is the gross margin.

Every item of a merchant has exactly one cost, shared across all inventory locations of that merchant. Several merchants sit under one organizer, and each merchant keeps its own cost. Moving stock from the central warehouse to the sales floor shifts quantity only; the money stays put.

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

The denominator of the weighted moving average is the merchant's total on-hand, accumulated across every location.

Why a hand-typed box does not solve this

A merchant buys the same item in batches at different prices: a carton of milk was VND 22,000 last month and VND 24,000 this month. If the system does not roll those batches into one number, the owner does the arithmetic on paper, and every profit report is wrong from the ground up.

A single box for the owner to type a cost into does not solve it either. A hand-typed number sits still even when goods arrive at a completely different price, so the longer it is used the further it drifts from what was actually paid, and the margin computed at the point of sale drifts with it.

So the system keeps two numbers side by side: the weighted moving average the system computes itself, and the standard cost the owner types in. The owner picks which one each item uses.

One item, end to end

Fresh milk. The location is empty. Two receipts at two prices, sell it all, then receive again.

What happens	On-hand	Stock value	Average cost
Receive 100 cartons at VND 20,000	100	VND 2,000,000	VND 20,000
Sell 40 cartons	60	VND 1,200,000	VND 20,000
Receive 40 cartons at VND 25,000	100	VND 2,200,000	VND 22,000
Sell the last 100 cartons, on-hand back to 0	0	VND 0	VND 22,000 (frozen)
Receive 50 cartons at VND 24,000	50	VND 1,200,000	VND 24,000 (replaced outright)

• Selling does not change the cost. Cost only changes at receipt: (1,200,000 + 40 × 25,000) divided by 100 is VND 22,000.
• On-hand reaching 0 freezes the old cost at VND 22,000. The system does not divide by zero and does not return a cost of 0.
• The next receipt replaces the old cost outright with the unit price of the new lot, because there is no old stock left to blend into.
• If this item is running a standard cost of VND 21,000, the gross margin on a sale is computed at VND 21,000, while the average-cost column still ticks along exactly as in the table above.

The easiest thing to get wrong

Per-location costing is one-way and cannot be turned off

A merchant whose purchasing is spread across locations can turn on an advanced setting so that each item-and-location pair carries its own cost.

Turning it on splits one number into many. Merging them back has no correct rule: averaging by quantity, or picking one location as the reference, is wrong for some merchant. So the system does not allow turning it off. The form says so plainly before the switch.

By default the cost is a single number for the whole merchant, and that is the right choice for nearly every merchant.

1. Goals & Non-goals

Goals

• One cost per merchant-and-item pair, not split by location.
• Store the weighted moving average (system-computed) and the standard cost (owner-entered) side by side, fully separated from the quantity table.
• Recompute the weighted moving average on every receipt, whatever method the item is currently on.
• Prevent division by zero when on-hand reaches zero or goes negative, by freezing the old cost.
• Write the difference between the actual receipt price and the standard cost onto the inventory ledger line, and roll it up into a screen over a date range.
• Handle a late vendor invoice with a price mismatch by adjusting forward, never recomputing the past.

Non-goals

• FIFO and LIFO valuation. Weighted moving average and standard cost only.
• Accounting entries, price variance accounts, and anything pushed into the Finance module.
• Retroactively recomputing the cost of issues that have already happened.
• The picking strategy used when stock leaves (earliest expiry first, first in first out). That is a separate setting owned by Lot, expiry & picking strategy and has nothing to do with how cost is computed.
• Multi-currency valuation.

2. Success metrics

Metric	Target / signal
Valuation correctness	The weighted moving average after each receipt matches a hand calculation on the same numbers
Recompute coverage	100% of receipts trigger a weighted-moving-average recompute
Divide-by-zero safety	No receipt leaves the cost meaningless when the prior on-hand was zero or negative
Gross margin trust	Gross margin on sales reports reflects what was actually paid, with no drift over time
Value of the variance screen	Merchants on standard cost open the variance screen and can explain why they paid more this month

3. Personas & scenarios

Persona	Goal in this feature
Owner	Know what one unit is worth, choose how it is costed, and look back at whether they bought above or below standard
Manager	Enter a standard cost for items with stable purchase prices or for goods produced in house
Cashier	Sell, and get correct gross margin on the report without configuring anything
System	Recompute the weighted moving average in the background on every receipt, and write the variance onto the ledger line

Core scenario: the owner opens the Inventory Valuation screen in the Client app, picks a method per item and types a standard cost where needed → goods arrive against a purchase order → the system recomputes the weighted moving average and writes the variance against standard onto the ledger line → when stock is issued, the number for the selected method is used to compute margin → at month end the owner opens the Cost Variance screen and sees the total paid above standard.

4. User stories

#	As a	I want	So that
01	owner	one cost per item even when the stock sits in several locations	I do not have to remember three numbers for the same carton of milk
02	owner	the system to roll batches bought at different prices into a single cost	I am not doing arithmetic on paper
03	manager	to type a fixed cost for items whose purchase price is stable	gross margin on the report does not jump with every receipt
04	owner	to decide per item whether it uses the computed cost or the one I typed	each item is costed the way it should be
05	owner	moving stock between my own locations to leave the cost untouched	shuffling goods around does not invent phantom profit or loss
06	owner on standard cost	to see how much more than standard I paid this month	I know whether to revise the standard
07	owner	a late vendor invoice with a different price to raise a flag rather than silently recompute my whole sales history	the reports I read last week do not change numbers on me

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	Each item a merchant carries has exactly one valuation record. • An item is either a product variant or a material. • Cost is not split per location: the same item sitting in the central warehouse, the sales floor and the bar counter shares one cost. • The stock table holds quantity only, never money.	🚧	URD-VAL-001
FR-002	The valuation record keeps two numbers side by side for each item. • Weighted moving average: computed by the system, not editable by the user. • Standard cost: typed by the owner, never changed by the system.	🚧	URD-VAL-002
FR-003	The owner picks the valuation method per item, and that choice decides which number is used when stock is issued. • The form shows two options: Weighted moving average (default) and Standard cost. • Every issue - a sale, a write-off, a BOM explosion - reads the cost for the selected method to compute gross margin and stock value.	🚧	URD-VAL-003
FR-004	The weighted moving average is recomputed on every receipt, whatever method the item is currently on. • An item running standard cost still gets its weighted moving average updated in the background. • That way the owner can switch methods at any time and always land on a correct number, instead of waiting for the next receipt.	🚧	URD-VAL-004
FR-005	The new average is computed over the merchant's total on-hand, not per location. • Formula: (prior stock value plus the value of the incoming lot) divided by (prior on-hand quantity plus the received quantity). • The denominator is the merchant-wide quantity, not the quantity at the receiving location.	🚧	URD-VAL-005 · URD-VAL-001
FR-006	When on-hand before the receipt is zero or negative, the system does not divide by zero. • The old cost is frozen and held until the next receipt. • The next receipt replaces the old cost outright with the unit price of the incoming lot.	🚧	URD-VAL-006
FR-007	The standard cost is typed by the owner on the Inventory Valuation screen in the Client app, and changes only when the owner edits it. • The Inventory Valuation screen is the only place to enter a standard cost: not on the item form, not on the stock screen. • Receipts never touch this number, whether the actual price came in above or below standard. • The standard cost and the weighted moving average are two separate numbers, shown as two separate columns on the Inventory Valuation screen.	🔶	URD-VAL-007
FR-008	The difference between the actual receipt price and the standard cost is written onto the inventory ledger line for that receipt. • The ledger line shows the actual receipt price, the configured standard cost, and the variance: positive means bought above standard, negative means below. • The variance is an observable number only. It generates no accounting entry and pushes nothing into the Finance module.	🚧	URD-VAL-008
FR-009	A stock transfer between two locations of the same merchant leaves the cost unchanged. • Only quantity moves between the two locations, the money stays put. • A transfer generates no profit or loss and writes no standard-cost variance line.	🚧	URD-VAL-009
FR-010	A vendor invoice that arrives after the receipt date carrying a different price is handled forward. • The purchase order raises a price mismatch warning showing both the price captured at receipt and the price on the invoice. • Issues that already happened keep their original cost, with no retroactive recompute. • If the owner confirms the new price, the cost is updated for subsequent receipts and issues.	🚧	URD-VAL-010
FR-011	The valuation method form offers two options only, with no FIFO and no LIFO. • The order in which lots are picked when stock is issued - earliest expiry, first in first out - is a separate setting and does not live on this form. • Changing the picking strategy does not change how cost is computed, and vice versa.	🚧	URD-VAL-011 · URD-LSE-005
FR-012	A merchant whose purchasing is spread across locations can turn on an advanced setting to split valuation per location. • Once on, each item-and-location pair carries its own cost instead of sharing one merchant-wide cost. • At switch-on, each location's cost is seeded from the existing shared cost. • The switch is one-way and cannot be turned off. Turning it on splits one number into many; merging them back has no correct rule - averaging by quantity, or picking one location as the reference, is wrong for some merchant. The form says so plainly before the switch.	🚧	URD-VAL-012
FR-013	The Cost Variance screen rolls up standard-cost variance over a date range. • The owner picks a date range and sees the total amount paid above or below the configured standard cost. • The total accumulates from the inventory ledger lines carrying a variance, and drills down to each item and each receipt. • The screen lists only items currently running standard cost.	🚧	URD-VAL-013

5.1 Acceptance criteria

• Open the Inventory Valuation screen for an item held in three locations → see exactly one cost for the merchant, with no per-location cost column.
• Open the Inventory Valuation screen for an item → see two numbers: the weighted moving average (read-only) and the standard cost (editable).
• Set the method to Standard cost for an item, type a standard cost of VND 20,000, then sell 1 unit → gross margin on the sales report is computed at VND 20,000, not at the average.
• An item holds 10 units at an average of VND 20,000 → receive 5 more at VND 26,000 → the new average reads VND 22,000, exactly (200,000 + 130,000) / 15.
• The same item is on Standard cost at VND 20,000 → receive 5 more at VND 26,000 → the average still updates to VND 22,000 in the background, while the cost used on sale stays VND 20,000.
• Sell the item down to zero on-hand, with the average previously at VND 22,000 → open the Inventory Valuation screen → still VND 22,000, no zero and no error.
• On-hand is zero, receive 8 units at VND 24,000 → the new average reads exactly VND 24,000, with nothing carried over from the old cost.
• Type a standard cost for an item on the Inventory Valuation screen, then receive goods three times at three different prices → reopen the screen → the standard cost still holds the number typed, only the weighted moving average has moved.
• An item on a standard cost of VND 20,000 is received at an actual price of VND 22,000 → open the inventory ledger → the receipt line shows the actual VND 22,000, the standard VND 20,000, and a variance of +VND 2,000 per unit.
• Transfer 5 units from the central warehouse to the sales floor → the item's cost is unchanged, only the quantities at the two locations move.
• Receive goods against a purchase order at VND 20,000, then record a vendor invoice at VND 21,000 → the purchase order raises a price mismatch warning; sales orders already closed keep their original gross margin.
• On that warning, confirm the new price → the cost follows VND 21,000 from the next receipt or issue onward, and nothing already recorded changes.
• Open the valuation method form → see only the two options Weighted moving average and Standard cost, with no FIFO and no LIFO.
• Turn on per-location valuation for the merchant → each location shows its own cost row, seeded from the shared cost as it stood before the switch; reopen the setting form → there is no control that turns it back off, and the screen states plainly that this is a one-way decision.
• An item on a standard cost of VND 20,000 is received three times in a month at VND 22,000, VND 21,000 and VND 23,000 for a total of 150 units → open the Cost Variance screen for that month → see the total paid above standard, drillable down to the three receipt lines.

6. Non-functional requirements

Aspect	Requirement
Data integrity	Recomputing the weighted moving average and increasing on-hand for the same receipt must succeed or fail together; there is no state where stock went up but the cost never moved
Concurrency	Two receipts of the same item landing at once must be applied one after the other on the valuation record, and the final result must equal the sequential result
Precision	Cost and stock value use 4-decimal precision
Merchant scoping	The valuation record is confined to the user's own merchant; reads and writes both require authentication
Traceability	Every change to a cost traces back to the inventory ledger line and the receipt document that caused it
One-way switch	Turning on per-location valuation is a one-way decision per merchant, and it must carry a rule for seeding each location's cost from the shared cost
i18n	Valuation method labels and variance column labels are bilingual

7. UX & flows

Cost recompute on receipt:

Cost selection when stock is issued:

The Inventory Valuation screen lives in the Client app and is aimed at the owner: every money figure for an item is typed here, while the stock screen only deals with quantity. One row per item, a read-only weighted-moving-average column, an editable standard-cost column, and a method picker. This is also the only place a standard cost can be entered; there is no equivalent field on the item form.

The Cost Variance screen is a separate screen with a date-range filter, listing only items currently running standard cost.

8. Data & domain

Concept	Role
Valuation record	One row per merchant-and-item pair, holding the weighted moving average, the standard cost and the selected method. It leaves room for a location, for merchants that turn on per-location valuation
Weighted moving average	The system-computed number, updated on every receipt
Standard cost	The number the owner types, never moved by a receipt
Valuation method	The owner's choice per item, deciding which number is used when stock is issued
Standard-cost variance	The gap between the actual receipt price and the standard cost, written on the receipt's inventory ledger line
Stock value	On-hand quantity times the cost in use. Stock value per location is the merchant's shared cost times that location's quantity

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	the merchant-wide on-hand quantity is the denominator of the weighted moving average.
02	PO Purchase orders	the unit price captured at receipt is the input to the recompute, and the purchase order is where the price mismatch warning appears when a vendor invoice arrives late.
03	LDG Inventory ledger	where the standard-cost variance is written, and where the Cost Variance screen accumulates its totals.
04	UOM Units of measure & conversion	cost is held in the base unit, so a unit price quoted per case must be converted to the base unit before it enters the formula.
05	Sale	the sale flow asks for the cost at checkout to compute gross margin.

Assumptions

#	Assumption	What breaks if it is wrong
01	The merchant accepts a single cost across their whole location network. Splitting by location is the exception and has to be turned on deliberately.	If splitting per location is the common case rather than the exception, the default is set wrong, and far more merchants than expected are pushed through a one-way decision.
02	Cost is locked in at the moment goods are received. A later invoice does not rewrite the past.	If accounting demands figures that match the invoice, every profit report already issued has to be recomputed retroactively, and the forward-only model in this version cannot deliver that.
03	The standard-cost variance is a number for the owner to read, not accounting data.	If the variance has to reach the accounting books, Inventory is forced to push entries into the Finance module, and the boundary between the two modules has to be redrawn.
04	An item that does not track stock has no valuation record.	An untracked item that still needs a gross margin would need another source of cost, and the profit report would be missing exactly that group of items.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory v2) - see the URD feature catalog
Rollout	All merchants. Per-location valuation is an opt-in setting per merchant
Migration	A merchant's cost is seeded from the current total stock value divided by the current total quantity, accumulated across all of that merchant's locations
Release criteria	The weighted moving average after each receipt matches a hand calculation; on-hand reaching zero does not corrupt the cost; a transfer leaves the cost unchanged; the Cost Variance screen totals correctly from the ledger lines
Monitoring	Number of items whose cost was updated against the total number of receipts, number of items running standard cost, and the gap between standard cost and weighted moving average per merchant

References

• URD: Inventory - Valuation
• Related: Stock items & levels · Inventory ledger · Purchase orders · Lot, expiry & picking strategy
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Cost sits frozen from data seeding onward, so gross margin on the sales report drifts further with every receipt at a new price	Recompute the weighted moving average on every receipt (FR-004, FR-005)
02	On-hand hitting zero and then being replenished can produce a division by zero and corrupt the cost	Freeze the old cost and replace it outright with the incoming lot's unit price (FR-006)
03	A merchant turns on per-location valuation and then wants to go back to a shared cost	Ratified: turning it off is not allowed (FR-012). Merging several costs back into one has no correct rule. The form warns before the switch, and this is a one-way decision.
04	Goods are priced per case but stock is held in cans, and a bad conversion throws the cost off by a multiple	The receipt unit price is always converted to the base unit before it enters the formula, using that item's own conversion factor
05	A merchant runs standard cost but nobody ever looks at the variance, so the standard drifts far from reality unnoticed	The Cost Variance screen rolls the numbers up over a date range so the owner can revise the standard (FR-013)
06	There is no rule yet for costing a finished good from the cost of its materials	Open: define the finished-good cost at production order completion, scoped to the Manufacturing feature

FAQ

#	Question	Answer
01	Why is cost not split per location by default?	Because quantity differs by location but money does not. A carton of milk moved from the central warehouse to the sales floor is still the carton you bought at that price. Splitting cost per location makes every transfer invent a phantom profit or loss. Merchants whose purchasing really is spread out and who genuinely need the split can turn on the advanced setting (FR-012) - but once it is on it cannot be turned off.
02	Why does the weighted moving average keep updating while I am on standard cost?	So a correct number is waiting for you whenever you change your mind. If it were only computed while the method was selected, the day you switched to weighted moving average the system would hand you a stale price from the last receipt before the switch, and that number is meaningless.
03	What happens to the cost when on-hand hits zero and I receive again?	The old cost is held while on-hand is zero, and the next receipt replaces it outright with the unit price of the new lot. There is no division by zero.
04	Does the standard-cost variance turn into an accounting entry?	No. It is a number written on the inventory ledger line for you to read and roll up by month. Inventory pushes nothing into the Finance module.
05	If a vendor invoice arrives later with a different price, do my old reports change?	No. Issues that already happened keep their original cost. The purchase order raises a price mismatch warning, and the new price applies only to subsequent receipts and issues.
06	Is there FIFO?	There is no FIFO and no LIFO for valuation. But there is an order for picking lots when stock is issued: earliest expiry first, or first in first out. Those are two different things. One decides which goods leave the shelf, the other decides the money attached to them.