Procure to pay
Spending money safely is a sequence of matches: the PO says what you agreed to buy, the receipt
says what arrived, the bill says what the supplier wants — and payment happens only where all three
agree. The API models each step explicitly; this guide connects them.
1 — Supplier and purchase order
The PO lifecycle is deliberate: submit → approve → send → acknowledge. Each is its own call
(POST /api/v1/purchase-orders/{id}/submit, /approve, /send, /acknowledge) because each is a
different actor — requester, approver, you-to-supplier, supplier-to-you. hold and cancel exist
at every stage before completion.
acknowledge is the step teams drop, and it’s the one that converts “we sent a PO” into “the
supplier has committed”. An unacknowledged PO past its expected-ack window is a supply risk you can
query for, not a surprise three weeks later.
2 — The goods arrive
Receiving has its own workflow — receiving and put-away
covers it fully. The short version: an inbound shipment arrives, a receipt records what was
actually in the boxes, and POST /api/v1/purchase-orders/{id}/receive ties the received quantities
back to the PO.
Received ≠ ordered is normal, not exceptional: short ships, overages, damage. The receipt captures
reality; the PO keeps the agreement. Keeping them separate is what makes step 4 possible.
3 — The bill arrives
4 — Three-way match
The engine compares PO ↔ receipt ↔ bill. Then branch:
The match is the control that stops the classic fraud and the classic mistake alike: paying for
quantity never received, or paying a price never agreed. Approve from the match result, not from
the PDF. A disputed bill blocks payment until resolved — that is the point, not an inconvenience
to route around.
5 — Pay in runs, not one-offs
A run gathers approved bills due in a window into one reviewable, approvable batch — one look at
total cash out instead of forty individual decisions. cancel works until process; after that,
a wrong payment is POST /api/v1/ap/payments/{id}/void and a corrected bill, not an edit.
Watching the whole pipe
AP aging is the mirror of AR aging: what you owe, by how overdue.
The useful discipline is watching disputed bills’ age separately — an old dispute is money you
probably owe and a supplier relationship quietly degrading.
