Workflow Playbook
Purchase Workflow and Stock/Cost Timing
Complete purchase workflow: what is required, what is optional, and exactly when stock and cost price are updated.
Audience: Procurement, warehouse, and accounts payable teams.
Collections and Responsibilities
Purchases
purchases
Primary procurement document for supplier invoice, statuses, and financial total.
Product Variants
productVariant
Receives stock increments and costPrice updates when delivery is posted.
Supplier Ledger
supplierBalance
Supplier payable ledger for purchase, purchase_update, and reversals.
Workflow Timeline
Step 1
Step 1: Create purchase header and lines
Set supplier and orderDate, add purchaseItems with quantity and unitPrice, then save.
Step 2
Step 2: Use status progression correctly
Draft/Ordered/Shipped do not move stock. Delivered is the only stock-posting stage.
Step 3
Step 3: Delivered posts inventory and cost
On delivered create/transition, variant stock increases and costPrice is updated from purchase unitPrice.
Step 4
Step 4: Payables are posted for non-draft documents
Supplier ledger entries are upserted on create/update when status is not draft.
Step 5
Step 5: Use reversals for corrections
Deleting purchase or changing supplier triggers reversal/adjustment logic to keep balances consistent.
Field Guide (Required vs Optional)
| Field | Requirement | Behavior |
|---|---|---|
Supplier supplier | Required | Mandatory payable owner for purchase. |
Order Date orderDate | Required | Required date field on purchase header. |
Status status | Auto / System | Defaults to draft on create; transition validation applies on update. |
Purchase Item Quantity purchaseItems[].quantity | Required | Must be >= 1 for each line. |
Unit Price purchaseItems[].unitPrice | Required | Must be >= 0; also drives variant costPrice updates on delivery. |
Tax Rate purchaseItems[].taxRate | Optional | Optional; leave empty for tax-exempt items. |
Purchase Totals subtotalAmount, taxTotalAmount, totalAmount | Auto / System | Server-side calculated before save. |
Delivery & Reference Details expectedDelivery, actualDelivery, invoiceReference, invoice, notes | Optional | Operational support fields and attachments. |
Payment Metrics amountPaid, paymentStatus, paymentPercentage | Auto / System | Read-only values derived from supplierPayments. |
Decision Scenarios
If this happens
Purchase is saved as draft
No stock update and no supplier payable posting.
Timing: On draft create/update.
If this happens
Purchase reaches delivered status
Variant stock increases and variant costPrice updates from line unitPrice.
Timing: afterChange when created as delivered or transitioned to delivered.
If this happens
User attempts to cancel delivered purchase
Request is rejected; return/reversal process must be used.
Timing: status beforeValidate.
If this happens
Purchase is deleted or supplier is changed
Supplier ledger applies reversal or reassignment adjustments.
Timing: afterDelete / afterChange ledger service.
Automatic Side Effects
- Tax and totals are recalculated server-side on every save.
- Delivery stage controls when stock and costPrice change.
- Supplier payable ledger is upserted/reversed automatically.
Operational Controls
- Treat delivered transition as controlled event because it posts inventory.
- Lock delivered purchases after approval in production governance.
- Prefer reversal entries over silent manual balance edits.