Purchase Orders

A Purchase Order (PO) is a request from a Customer to a Vendor to purchase goods. When accepted by the vendor, it becomes a contract for supply of goods subject to the terms and conditions in the order.

Domain Concepts

Organization: A legal entity that can enter into contracts with other organizations — companies, departments, government agencies, etc.

Contact: A person who can act on behalf of an organization.

Vendor: An organization that commercially offers goods for sale.

Customer: An organization that commercially acquires goods.

Supplier: An organization that fulfills goods in response to a commercial transaction. In the context of a Purchase Order (for the current scope), Vendor and Supplier are assumed to be the same organization.

Consumer: An organization that receives goods resulting from a commercial transaction. In the current scope, Customer and Consumer are assumed to be the same organization.

Carrier: The organization responsible for the physical transfer of goods from a supplier to a consumer. Specifically, the party presenting the Bill of Lading at delivery. For the current scope, carriers are often left unspecified.

Purchase Order Line (PoLine): Specifies a quantity of a given item to be purchased within the context of a PO, including unit price, total price, and any item-specific information not already in the PO header.

PurchaseOrder Entity

A Purchase Order is a journaled entity scoped to a tenant. All fields become read-only once the order leaves the NEW state, except for privateNotes.

Field	Type	Default	User Editable	Description
`status`	PoStatus	`NEW`	No	Current lifecycle state
`orderNumber`	String	Auto-generated (`PO#####`)	No	Human-readable order identifier
`orderDate`	Date	Creation date	Yes	Date the order is submitted
`allowPartial`	Boolean	`true`	Yes	Whether partial deliveries are accepted
`deliverBy`	DateTime	Creation date	Yes	Expected complete delivery date
`deliveryAddress`	Address	Blank (future: from tenant/facility)	Yes	Delivery destination
`procurement`	Contact	Current user	Yes	Customer-side contact for the order
`supplierName`	String	From lines if available	Yes	Supplier responsible for fulfillment
`supplierAddress`	Address	From lines if available	Yes	Supplier’s address
`orderMethod`	OrderMethod	`UNKNOWN` or from lines	Yes	How the order is submitted to the supplier
`sales`	Contact	From supplier info if available	Yes	Vendor-side contact for the order
`goodsValue`	Money	Calculated	No	Sum of all PoLine values
`taxesAndFees`	Map of String to Money	Empty	Yes	Additional charges (delivery fees, taxes, etc.)
`totalAmount`	Money	Calculated	No	`goodsValue` + all `taxesAndFees` entries
`termsAndConditions`	String	Blank	Yes	Free-form T&C text
`notes`	String	Blank	Yes	General notes (included in vendor communication)
`privateNotes`	String	Blank	Yes	Internal notes (not shared with vendor)

PoLine Entity

Each PoLine specifies one item quantity within a purchase order. PoLine status is a computed (transient) state not stored explicitly, to avoid updating all lines when item data changes.

Field	Type	Description
`status`	PoLineStatus	Current computed state of the line
`item`	Reference to Item	The item being ordered
`supplierSku`	String	Vendor’s SKU for the item (from item supply info)
`quantity`	Quantity	Amount ordered
`unitCost`	Money	Cost per unit
`cost`	Money	Total cost (`unitCost × quantity.amount`)
`received`	Quantity	Amount received against this line
`notes`	String	Instructions or communication to the vendor
`privateNotes`	String	Internal notes not shared with the vendor

All fields except notes and received become read-only once the order is submitted.

Order Lifecycle

Order States

State	Description
`NEW`	Order created; being edited and defined
`APPROVED`	Order finalized within the customer organization; ready to send to vendor
`SUBMITTED`	Order sent to the vendor
`IN_PROCESS`	Vendor has started processing; goods are expected
`PARTIALLY_RECEIVED`	Some goods have been delivered but not all
`RECEIVED`	All goods have been delivered
`CLOSED`	Order marked complete by the customer; accounting effects triggered
`CANCELLED`	Order cancelled before fulfillment or after (vendor accepted cancellation)
`REJECTED`	Customer has rejected some or all delivered goods
`DISPUTED`	Disagreement between vendor and customer about fulfillment

Order Signals

Signal	Description	Effects
`approve`	Mark the order as APPROVED	Fields and lines become read-only
`submit`	Send the order to the vendor	System actions depend on `orderMethod`; transitions to SUBMITTED
`ship`	Vendor has started fulfillment	Transitions to IN_PROCESS
`receive`	Goods received against the order	Records received quantities; transitions to PARTIALLY_RECEIVED or RECEIVED
`complete_receive`	All expected goods received	Transitions to RECEIVED
`cancel`	Cancel the order	Transitions to CANCELLED
`reject`	Customer rejects delivered goods	Transitions to REJECTED
`dispute`	Register a fulfillment disagreement	Transitions to DISPUTED
`close`	Mark the order complete	Transitions to CLOSED; triggers accounting effects

Composite Signals

Some signals are composites of elementary signals:

submit from NEW is equivalent to [approve, submit]
complete from any state is the shortest valid sequence to reach CLOSED

Order Line Lifecycle

State	Description
`BLANK`	Line created with no item assigned
`CURRENT`	Item assigned and up to date
`STALE`	Item has been modified since it was added to the line
`INVALID`	Item has been deleted
`RECEIVING`	Order submitted; receiving in progress
`COMPLETED`	Line fully received

Relationship to Kanban Cards

Purchase order lines carry a demand relationship to kanban cards. When an order is created from the order queue (a set of cards in REQUESTED state), the PoLines are associated with the cards that triggered them. When the order is received, the associated cards advance through the fulfillment portion of the kanban lifecycle.

See Kanban Cards for the card state model.

Excluded from this document: REST API endpoint specifications, request/response schemas, filtering/pagination parameters, and the complete list of current implementation constraints belong in the Current System section. The tracking information (GitHub issues, milestones) is also excluded as it is implementation-level project tracking.