PRD: Vendors

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

What a vendor is

A merchant buys from many places. A vendor is the profile of one party selling to that merchant: name, tax code, address, transaction currency, and a list of contacts.

Knowing a vendor's name is not enough to raise a correct purchase order. So every vendor - item pair is its own record, carrying all the purchasing data for that item at that particular vendor: the ordering unit, the minimum order quantity, the lead time, the price tiers, the vendor's own item code, and the last purchase price.

The conversion factor lives on the item, not on the vendor

Quoted from Units of Measure & Conversion so nobody has to open another PRD. Every item has a base unit - the smallest unit it is counted in, and all stock is always held in that unit. A conversion factor ("1 case = 24 cartons") is a fixed property of a unit on that item.

A vendor row carries no factor of its own. It only points at a unit already declared on the item. That is what makes it impossible for two vendors to disagree about how much a case holds.

Why the purchase price is not on the item

The same case of milk carries a different price, a different minimum order quantity, and a different lead time at every vendor. At a single vendor, every item has its own packaging. With nowhere to store those numbers, the owner has to hold them in their head or scroll back through Zalo messages every time they order, and a new employee simply cannot place an order at all.

Purchase price is also not sale price. What the customer pays lives in the Pricing module and travels with the product variant. What the merchant pays travels with the vendor - item pair, and the same item bought in two places has two prices. Mixing the two into one field is the root of every wrong margin number.

One item, two vendors, end to end

The material "Fresh milk", base unit carton. Vendor A sells by the Case of 24, vendor B by the Case of 12.

What happens	Price suggested on the line	Vendor A's last purchase price	Fresh milk stock
Link Fresh milk to A, enter tiers: 50,000d from 10 cases, 46,000d from 50 cases	-	none yet	0 cartons
Raise a purchase order for 12 cases from A	50,000d (the 10-case tier)	none yet	0 cartons
Receive the goods, the real price is 55,000d	-	55,000d	288 cartons
Raise a purchase order for 5 cases from A, no tier matches	55,000d (last purchase price)	55,000d	288 cartons
Raise a purchase order for 2 cases from B, the item is not linked to B	blank, the merchant types it	55,000d	288 cartons
Receive B's goods	-	55,000d	312 cartons

• 12 cases from A produce 288 cartons (12 x 24). 2 cases from B produce 24 cartons (2 x 12). The factor comes from the unit on the item, never from the vendor row.
• The last purchase price is recorded at receipt, not at order. Order at 50,000d and receive at 55,000d, and the number stored is 55,000d, because that is the money actually paid.
• A tier wins when the quantity being ordered matches one. When no tier matches, the last purchase price is used.
• A's record and B's record exist side by side, each holding its own price.

The easiest thing to get wrong

A vendor with a different pack size gets a new unit, not an edited factor

Vendor B sells cases of 12 cartons while the item's Case is 24. The right move is to declare a new Case of 12 unit on the item, then point vendor B's row at that unit.

Editing the Case factor from 24 down to 12 rewrites history: every past receipt from A changes meaning. The factor is locked the moment an item has any stock movement.

The consequence: "5 cases from this vendor" always resolves to exactly one number, including during a stock count or a transfer, when nobody remembers which vendor the goods came from.

1. Goals & Non-Goals

Goals

• Manage Vendor profiles per merchant, each with multiple contacts.
• Hold the purchasing data on each vendor - item pair: last purchase price, minimum order quantity, lead time, ordering unit, vendor item code.
• Let merchants enter price tiers by order quantity and mark one preferred vendor per item.
• Refresh the last purchase price automatically on every receipt, with nobody retyping it.
• Feed that data into the purchase-order screen so a line arrives with its price and unit already filled in.

Non-Goals

• The purchase-order lifecycle, partial receipts, and price-variance warnings - owned by the Purchase order feature.
• Accounts payable to vendors, payment terms, and financial invoice reconciliation - owned by the Finance module.
• Weighted moving average (AVCO) and standard cost - owned by the Inventory valuation feature.
• The price the customer pays - owned by the Pricing module.
• Vendor scorecards and delivery-performance ratings.

2. Success Metrics

Metric	Target / signal
Purchasing-data coverage	The share of items with at least one vendor - item record climbs month over month
Quality of the suggested price	Most purchase-order lines keep the suggested price untouched
Price freshness	The last purchase price always matches the unit price of the most recent receipt
Clear preference	Every regularly purchased item has exactly one vendor marked as preferred

3. Personas & Scenarios

Persona	Goal in this feature
Merchant owner	Enter vendors and their purchasing terms, and decide who is the preferred source for each item
Warehouse manager	Raise purchase orders fast, without having to ask again for the price or the minimum order quantity
Operations team	View and edit a merchant's vendor profiles in the Back Office when supporting them
System	Write the real price back to the vendor - item record on every receipt

Core scenario: the owner of a bubble-tea merchant creates the vendor "Ba Vi Milk" with a contact and a tax code, links the material "Fresh milk" to that vendor, enters a case of 24 cartons, a minimum order of 2 cases, delivery in 3 days, and marks this as the preferred source. A month later they raise a purchase order, pick "Ba Vi Milk", add the "Fresh milk" line, and the price and unit are already there. The goods arrive at 55,000d a case, the record updates itself with the new price, and the next order suggests exactly 55,000d.

4. User Stories

#	As a	I want	So that
01	merchant owner	to keep a vendor profile with several contacts on it	anyone on the team can reach the right person when an order needs placing
02	merchant owner	to enter the price and purchasing terms per vendor - item pair	the same item bought in two places keeps two different prices
03	merchant owner	to enter the minimum order quantity and the lead time	the system reminds me to order enough and I know when the goods land
04	merchant owner	to enter price tiers by quantity	ordering more actually gets me the lower price the system calculates
05	merchant owner	to mark one preferred source per item	whoever places the order knows who to call by default
06	warehouse manager	purchase-order lines to arrive with their price and unit filled in	I do not retype them and do not mistype them
07	warehouse manager	to see the vendor's own item code	I can reconcile it against the delivery note they hand over
08	system	to record the real price on every receipt	the next suggested price is never out of date

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	A merchant owner creates and edits Vendors on the Client app; the operations team does the same in the Back Office. • Required: vendor name. • Optional: description, tax code, address. • A contact list, each contact with a name (required), an email and a phone number (optional); several contacts fit on one profile. • Transaction currency: VND.	✅	URD-VEN-001
FR-002	A vendor has three statuses: Active, Inactive, Archived. • A newly created vendor defaults to Active. • The vendor list screen is scoped to the merchant and carries a status filter plus a search box on name or tax code.	🔶	URD-VEN-009
FR-003	Every Vendor - item pair is its own record, and it is the official source of purchasing data for that item. • One item can be linked to many vendors; one vendor can carry many items. • A given vendor and item pair has exactly one record; linking the same pair a second time edits the existing record rather than creating a duplicate. • The purchasing data on this record is entirely separate from the sale price of the same item. • A linkable item is either a product variant or a material.	🔶	URD-VEN-002
FR-004	The Vendor - item record carries the ordering terms. • Minimum order quantity: ordering below this number raises a warning on the purchase-order screen. • Expected lead time, in days from the order date. • Ordering unit: pick one of the units already declared on the item itself, for example this vendor sells by the Case of 10. • The vendor row carries no conversion factor of its own. The factor is a fixed property of a unit on the item, so two vendors can never disagree about how much a case holds. • A vendor that ships a different pack size gets a new unit on the item (Case of 10 alongside Case of 12), and the vendor row points at that unit. That way "5 cases from this vendor" always resolves to one number, including during a stock count or a transfer, when nobody remembers which vendor the goods came from.	🔶	URD-VEN-003
FR-005	The Vendor - item record holds the last purchase price and refreshes it after every receipt. • What is stored: unit price, unit of measure, order time, receipt time. • Every time a purchase order for that pair is received, the last purchase price is overwritten with the unit price and unit of that receipt, along with the new timestamp. • With several receipts against one order, the final receipt is the one that decides the stored price. • The last purchase price shows on the record and on the order line when a new purchase order is raised.	🔶	URD-VEN-004
FR-006	A merchant owner marks one vendor as preferred for a specific item. • An item has at most one preferred vendor at any moment. • Marking a new vendor automatically clears the mark on the previous one, with no extra step. • The preferred vendor is the default suggestion when a purchase order is raised for that item, not a hard constraint.	🔶	URD-VEN-005
FR-007	The Vendor - item record supports price tiers by order quantity. • Each tier carries a minimum quantity, a unit price, and its own unit of measure, plus an optional note. • Several tiers fit on one record, for example 50,000d from 10 cases and 46,000d from 50 cases. • The tier applied is the one with the highest minimum quantity that is still at or below the quantity being ordered; if no tier matches, the last purchase price is used.	🔶	URD-VEN-006
FR-008	The Vendor - item record holds the vendor's own item code, distinct from the internal one. • The vendor's own name for the item is stored alongside it. • That code appears on the purchase-order line, to reconcile against the delivery note or the invoice the vendor hands over.	🔶	URD-VEN-007
FR-009	Raising a purchase order picks one vendor, and every line added pulls in the purchasing data of that vendor - item pair. • Suggested unit price: the tier price when the order quantity matches a tier, otherwise the last purchase price. • Suggested unit of measure: the ordering unit that was entered. • The merchant can edit both the price and the unit before saving the line. • An item with no record against the selected vendor leaves the price blank for the merchant to type, and the first receipt creates the purchasing data for that pair.	🚧	URD-VEN-002 · URD-PO-004
FR-010	Vendors and Vendor - item records are private to each merchant. • Every record is confined to the user's own merchant. • Deletion is a soft delete and is recoverable; the item records attached to a vendor survive for historical lookup.	✅	URD-VEN-008

5.1 Acceptance criteria

• Create a vendor filling in nothing but the name → the profile saves and its status shows Active.
• Add two contacts to one profile (one with an email, one with only a phone number) → reopening the profile shows both contact rows.
• Set a vendor's status to Inactive, then filter the list by Active → that vendor is no longer in the results.
• Type a tax code into the vendor list search box → the vendor carrying that tax code comes up.
• Link the material "Fresh milk" to vendor A → a vendor - item record is created; link the same pair again → no second record appears, the existing one is edited instead.
• Link the same "Fresh milk" to vendor B → both the A and the B records exist side by side, each holding its own price.
• Enter a minimum order quantity of 2 cases on the A - "Fresh milk" pair, then raise a purchase order for 1 case → the order screen warns that the quantity is below the minimum.
• Declare packaging of 1 case equals 24 cartons for the A - "Fresh milk" pair, then receive 2 cases → on-hand stock of "Fresh milk" rises by 48 cartons, correct in the base unit.
• The B - "Fresh milk" pair declares no packaging of its own, while the material "Fresh milk" states 1 case equals 12 cartons → receiving 2 cases from B raises stock by 24 cartons, that is, the factor declared on the material is used.
• The A - "Fresh milk" record holds a last purchase price of 50,000d; receive a purchase order from A at 55,000d → reopening the record shows 55,000d and the new receipt time.
• Receive the same order in two batches, the second one at 57,000d → the last purchase price on the record is 57,000d.
• Mark vendor A as preferred for "Fresh milk", then mark B as preferred for the same item → A loses the mark automatically and only B carries it.
• Enter two price tiers on the A - "Fresh milk" pair (50,000d from 10 cases, 46,000d from 50 cases), then raise an order for 60 cases → the suggested unit price is 46,000d; order 12 cases → 50,000d is suggested; order 5 cases → the last purchase price is suggested.
• Enter the vendor item code "MILK-BV-24" on the A - "Fresh milk" pair → the matching purchase-order line shows "MILK-BV-24" next to the internal code.
• Raise a purchase order, pick vendor A, add the "Fresh milk" line → the unit price and unit of measure fields already hold the values from the A - "Fresh milk" record; edit the price by hand and save → the line keeps the edited price.
• Add an item to the same order that has never been linked to A → the unit price field is blank, can be typed into, and saves normally.
• Sign in as a user of another merchant → none of the first merchant's vendors appear.
• Delete a vendor that still has item records attached → the profile disappears from the list, but this is a soft delete, and the purchasing data on the vendor - item pairs survives for historical lookup and can be restored.

6. Non-Functional Requirements

Aspect	Requirement
Data integrity	"One record per vendor - item pair" and "one preferred vendor per item" are enforced at the database layer, not left to the discipline of the code
Merchant scoping	Every vendor and vendor - item record is confined to the user's own merchant and uses soft delete
Precision	Unit prices and quantities are stored to 4 decimal places; the packaging conversion factor is captured on the line at receipt time, so historical prices do not shift when a merchant edits the packaging later
Concurrency	Two people marking a preferred vendor for one item from two machines still end up with exactly one preferred vendor, never a two-mark state
Performance	The purchase-order screen fetches the purchasing data for all of its lines in a single call, not one call per line
i18n	Vendor names and descriptions are stored bilingually

7. UX & Flows

The Vendors screen sits under the Inventory group on the Client app for the merchant owner, and in the Back Office for the operations team supporting a merchant. A vendor's items are linked and their purchasing terms entered right inside the vendor form, saved together with the profile in one click.

8. Data & Domain

Concept	Role
Vendor	The party selling to the merchant: name, description, tax code, currency, address, status, contact list
Contact	A person on the vendor's side: name, email, phone; one vendor has several contacts
Vendor - item record	The purchasing data for one item at one vendor: minimum order quantity, lead time, ordering unit, preferred mark, status
Last purchase price	A snapshot of the most recent receipt: unit price, unit of measure, conversion factor, order time, receipt time
Price tier	One price step by order quantity: minimum quantity, unit price, unit of measure, note
Vendor item code	The item code and name as the vendor calls them, used to reconcile the documents they hand over
Item	What is being purchased: a product variant, or a material

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	PO Purchase orders	where the purchasing data is read to suggest a price, and where the real price is written back after a receipt.
02	UOM Units of measure & conversion	the units declared on an item, and the fixed factor each one converts by. The vendor row only points at one of them.
03	MAT Materials and product variants (Products module)	the two kinds of item that can be linked to a vendor.
04	Merchant	every record is confined to the user's own merchant.

Assumptions

#	Assumption	What breaks if it is wrong
01	Buying one item from several vendors is normal, and each of them has its own price.	Forcing one purchase price per item destroys the merchant's ability to compare sources, and every margin number is computed against a price that does not exist.
02	The last purchase price is a good enough indicator for the next order; the merchant can still edit it by hand before sending the order.	One urgent high-priced buy drags every later suggestion with it, and a merchant who does not correct it orders at the wrong price every time.
03	A conversion factor is a fixed property of a unit on the item itself. The vendor - item record carries no factor of its own and never overrides that number. A vendor who packs a different case size gets a new unit on the item (Case of 10 alongside Case of 12), and the vendor row points at that unit.	Letting a vendor row carry its own factor lets two vendors disagree about how much a case holds, and during a stock count or a transfer - when nobody remembers which vendor the goods came from - no number is correct any more.
04	Contacts on the vendor's side are not login accounts in the system.	Treating a contact as an account demands its own identity, permissions and lifecycle, none of which is in this model.

10. Release Plan & Criteria

Aspect	Plan
Phase	P2 (Inventory) - see the URD feature catalogue
Rollout	All merchants; no feature flag
Migration	Existing vendor data is untouched; older vendor - item records without a minimum order quantity or price tiers stay blank, and merchants fill them in over time
Release criteria	Vendors can be created and edited with several contacts; items can be linked with a minimum order quantity, lead time, ordering unit, price tiers, and vendor item code; the preferred mark moves correctly; a receipt refreshes the last purchase price; purchase-order lines arrive with their price and unit filled in
Monitoring	Number of items with a vendor record, share of lines that keep the suggested price, number of times the last purchase price is refreshed by a receipt

References

• URD: Vendors
• Related: Purchase orders · Units of measure & conversion · Materials · Inventory valuation
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A merchant wants to edit a conversion factor (1 case of 24 cartons becomes 12) after the item already has stock movement	The factor is locked the moment an item has any stock movement (Units of measure, FR-015). A different pack size means a new unit, never an edited one. Documents also freeze the factor when they are raised, so history does not move with it (§6).
02	The last purchase price is skewed by one unusual receipt (an urgent buy at a high price), dragging every later suggestion with it	The merchant can edit the price on the line before sending the order (FR-009); price tiers are the steadier number to lean on
03	Two records for the same vendor - item pair, created by a duplicate action	A unique constraint at the database layer on the vendor and item pair (§6)
04	When a vendor's currency is not VND, how are the last purchase price and the price tiers converted at order time	Open: whether the exchange rate is taken at order time or at receipt time will be decided together with multi-currency in Purchase orders
05	Payment terms with a vendor (pay on delivery, net N days, end of month) are currently only free-text notes on the profile	Open: to be promoted to first-class data when the Finance module builds accounts payable

Frequently asked questions

#	Question	Answer
01	Why is the purchase price not simply held on the item?	Because the same item bought from two vendors means two prices, two minimum order quantities, two lead times. Putting the purchase price on the item only holds one set of numbers, and the merchant loses the ability to compare sources at all.
02	How is the purchase price different from the sale price?	What the customer pays travels with the product variant and is owned by the Pricing module. What the merchant pays travels with the vendor - item pair and is owned here. Two independent numbers, neither derived from the other.
03	When is the last purchase price refreshed?	At receipt, not at order. If you order at one price and the goods arrive at another, the number stored is the one actually received, because that is the money the merchant really paid.
04	Can an item have several preferred vendors?	No. One at most. Marking a new one clears the old one automatically, with no manual unmarking.
05	Price tier or last purchase price - which wins on an order?	The tier wins when the quantity being ordered matches a tier. When no tier matches, the last purchase price is used.
06	If a vendor goes Inactive, do their item records disappear?	No. The purchasing data stays intact for historical lookup; that vendor simply stops being suggested on new orders.