Skip to main content

Purchase Order lifecycle

A PO moves from the shop's draft to a vendor confirmation to physical receipt. The lifecycle tracks both the procurement side (when did we order, did we get it) and the finance side (did we pay, what's the balance).

Drafted from planning · v0.1

Slice 6 (Purchase Orders) is schema-complete; UI not built.

States and transitions​

State definitions​

StateWhat it means
draftPO being assembled by staff; not yet sent to vendor
sentPO transmitted to vendor; awaiting confirmation
confirmedVendor has acknowledged and committed to fulfill
partialSome items have been received; PO is open until full
receivedAll items received; awaiting invoice reconciliation
reconciledVendor invoice matched against PO; payment due/scheduled
cancelledPO cancelled at any point before fulfillment

Behaviors​

Creation paths​

From low-stock alert: the daily-cron low-stock report has a "Create PO" button per vendor that pre-fills a draft.

Manual: Settings → Purchase Orders → New, pick vendor, add SKUs from inventory.

From vendor API (when wired for QBP, Shimano, etc.): wholesale stock checks become PO drafts directly.

Transmission​

POST /api/pos/{id}/send:

  • Generates a PO email (or API call for integrated vendors)
  • Records the timestamp + recipient
  • Transitions state to sent
  • Audit-logged

Receiving​

POST /api/pos/{id}/receive:

  • Body: { lines: [{ po_line_id, qty_received }] }
  • Updates purchase_order_lines.qty_received
  • Updates inventory_variants.qty_on_order (-) and qty_on_hand (+)
  • If all lines fully received, transitions to received; else partial

Reconciliation​

POST /api/pos/{id}/reconcile:

  • Body: { invoice_number, invoice_total_cents, lines: [{ po_line_id, unit_cost_cents }] }
  • Compares invoice to PO; flags mismatches for the operator to resolve
  • On match, transitions to reconciled
  • Generates an A/P entry (for the shop's accountant export)

Audit​

Every transition writes audit rows. The PO is one of the longest-living entities (can span weeks); the audit trail is the only complete record of who placed what when, who confirmed, what arrived in which shipment.

See also​