Purchase Order
What it is
One purchase order in full: its header figures, its signing state, its lines, and every delivery challan raised against it. It is also where you turn the order into a customer invoice once goods have moved.
Who can open it
Any signed-in staff account that is active, subject to the same two gates as the
Purchase Orders list — an active account, and the ops.purchase-orders feature grant
while FEATURE_GRANULAR_RBAC is on. The owner bypasses the grant.
Within the signing panel, who you are matters. Only the person named as approver on this order sees the signing window and the Reject button; everybody else sees a line saying the order is waiting on them. An approver may not be the person who created the order.
Before you start
⚠️ Two actions people expect to find here are not on this screen. Emailing the order to the supplier and marking it received are both on the Purchase Orders list, as row actions. This screen has no send button and no receive button.
"Delivery State" reads pending when it has never been set. The list's Delivery dropdown only
offers Open / Partial / Complete / Cancelled, so pending here means nobody has touched it, not
that a fifth state exists.
Every control on the page
Header, top right:
| Control | When it appears | What it does |
|---|---|---|
| ✎ Edit Record | Always | Goes to Edit Purchase Order. The edit screen, not this one, decides whether the order may still be changed |
| Preview Invoice | Only when Delivery State is partial or complete and at least one delivery challan is dispatched or delivered | Opens the invoice preview panel |
| Variance Pending | Same conditions, but any billable challan carries a variance flag | The same button, coloured orange. It still opens the preview; generating from it is what is blocked |
Header card — four cells: Date, Amount (with currency), Status (draft / issued / fulfilled / cancelled) and Delivery State. The order's notes, if any, run along the bottom of the card.
Signing Status panel. This panel is live only while PO e-signing is switched on. It is switched on in production, and the database columns it needs are in place. What it shows depends on the order's signing status:
| Status | What you see |
|---|---|
| pending (or never set) | "Select an approver and send this PO for digital signature", an approver dropdown, and Send for Approval. The person who created the order is excluded from the list. With nobody eligible it reads "No approvers configured — add them in Settings → PO Approvers" |
| out_for_signature, and you are the approver | The signing window embedded in the page, plus a Reject button that asks for a reason in a browser prompt. A reason is required — cancel or leave it blank and nothing happens |
| out_for_signature, and you are not | "Waiting for the assigned approver to sign this PO." |
| signed | "This PO has been signed and is ready to send to the supplier", and Download Signed PDF → when a signed file exists |
| rejected | The rejection reason in red, "Edit the PO if needed, then resend for approval", and an approver dropdown with Resend for Approval |
⚠️ The panel does not refresh itself. After a successful send it says "Sent for approval. Reload the page to see the updated status" — and it means it. The badge above stays on the old value until you reload.
Line Items — Description, Qty, Unit, Unit Cost, Line Total. The whole table is hidden when the
order has no lines, rather than showing an empty table. A line carrying a dangerous-goods
declaration shows a red second line under the description: ⚠ IMDG class | UN number |
PG group, and Marine Pollutant where that is set.
Delivery Challans (N) — the roster of challans raised against this order:
| Column | Notes |
|---|---|
| DC # | Links to the challan |
| Status | draft / loaded / dispatched / delivered / cancelled |
| Dispatched, Delivered | Dates, or — |
| Lines | How many item rows the challan has |
| Invoice | View Invoice → once the challan has been invoiced, otherwise — |
| Variance | An amber ⚠ Variance where a quantity variance was detected |
Create DC sits in the panel header and again in the empty state; both carry this order's id, so the challan screen opens already pointed at this order. The empty state reads "No delivery challans yet".
What it writes
This screen writes nothing on its own. Loading it reads the order, its lines and its challans. Everything that writes is behind one of the buttons:
Send for Approval calls POST /api/purchase-orders/[id]/send-for-signature. It refuses an order
already out_for_signature or signed, refuses an approver who is not registered for the order's
entity or who created the order, and refuses an approver with no email address. On success it moves
the order to out_for_signature and records the approver.
Reject calls POST /api/purchase-orders/[id]/reject-signature with your reason, which is then
shown on the panel.
Generating the invoice — from inside the preview panel — calls POST /api/invoices/from-po with
today's date and payment terms of 30 days, both fixed by this screen. On success you are taken
straight to the new invoice.
When it goes wrong
"Signature service unavailable; PO left unchanged." The signing service is not reachable or not configured. Nothing about the order changed, so nothing needs undoing. This is the expected answer while the signing back end is parked.
"No approvers configured — add them in Settings → PO Approvers." Either nobody is registered as an approver for this entity, or the only one registered is you — the creator of an order can never approve it.
"PO already out_for_signature" / "PO already signed". Someone else has already sent it. Reload.
The signing badge did not change after sending. Expected — reload the page.
There is no Preview Invoice button. Either the Delivery State is not partial or complete, or
no challan against this order has reached dispatched or delivered. Both must be true.
The button reads "Variance Pending". A billable challan has an unapproved quantity variance. Resolve it on that challan; generating is refused until you do.
Errors from generating an invoice are shown in plain words rather than codes — among them "Delivery challans have mixed currencies — cannot consolidate", "No billable delivery challans (need dispatched or delivered status)", "An invoice already exists for this PO" and "Unapproved quantity variance detected."
"Purchase order not found." The order does not exist, or it belongs to an entity your permissions do not cover.
Related screens
- Purchase Orders — the list, and the only place to email or receive this order.
- Edit Purchase Order — changing it, and when you may not.
- Delivery Challans — the dispatches listed here.
- Create Delivery Challan — where Create DC goes.