Sales Orders

Approval Workflow

Which status can move to which, and who is allowed to move it. These rules are enforced on the server, not just in the screen.

Last updated 2026-10-13

DigitalKey ERP — Docs · digital-key.co/docs/sales-orders/approval-workflow

Status flow

In standard mode an order travels:

Standard workflow
draft ──► pending ──► approved ──► completed
  ▲          │            │
  └──────────┘            │        (reject → back to draft)
  └───────────────────────┘

any status ──► void   (needs "Void orders")

In simple mode the middle disappears — an order goes straight from draft to completed, a move that needs Complete orders.

Sales Orders — Order detail with status actions
Order detail with status actions
Order detail with status actions — An open order showing its current status and the actions available to the signed-in role.

Allowed transitions

This is the complete set. Anything not listed is refused, whatever your role — the server returns a 403 naming the role and the transition it rejected.

FromToPermission neededMeaning
draftpendingAnyone who may use sales ordersSubmit for approval
draftcompletedComplete ordersComplete directly, skipping approval
pendingapprovedApprove / reject ordersApprove
pendingdraftApprove / reject ordersReject, back for changes
approvedcompletedComplete ordersFulfil the order
approveddraftComplete ordersReject an already-approved order
any except voidvoidVoid ordersCancel the order
Rejection is not one permissionRejecting from pending needs Approve / reject orders, but rejecting an order that has already been approved needs Complete orders. Someone can send back what is waiting on them without being able to undo an approval.
NoteApprove and Completeare separate rows in the matrix, so a user can be allowed to approve an order but not to fulfil it. The owner always has both. A new staff account starts with all five order permissions switched off — approve, complete, void, see everyone's orders, and edit a completed order.

Changing status

PUT /api/v1/sales-orders/{id}/status
ParameterTypeRequiredDescription
new_statusstringRequiredOne of draft, pending, approved, completed or void.
reasonstringOptionalWhy. Recorded on rejections and voids, and always written to the log.
NoteMoving an order to the status it is already in is refused. The status change and everything it triggers happen in one transaction — a completion that cannot move stock leaves the order untouched rather than half-applied.

When stock moves

ImportantStock is deducted only when an order reaches completed. Draft, pending and approved orders have no effect on stock whatsoever and reserve nothing. An approved order is a promise, not a hold — the goods can still be sold at the counter before it is completed.

What completion checks first — any one of these refuses it and leaves the order as it was:

  • Stock — every product must be in stock for the full quantity.
  • Credit limit — the unpaid part must fit the customer's limit.
  • Price — a typed price may not be below the product's cost today.

What completion then does:

  • Deducts every line from stock (a carton line as its pieces).
  • Stamps each line with the product's cost at that moment — the cost its profit is measured against from then on.
  • Updates the customer balance for the unpaid portion.
  • Makes the order appear in sales figures and reports.

Voiding a completed order reverses all of that, returning the stock at the cost it left at. Voiding at any earlier status simply closes it.

What is recorded

ParameterTypeRequiredDescription
approved_byintegerOptionalUser who approved it.
approved_attimestampOptionalWhen it was approved.
rejected_byintegerOptionalUser who rejected it.
rejected_attimestampOptionalWhen it was rejected.
reject_reasonstringOptionalThe reason given on rejection.
void_byintegerOptionalUser who voided it.
void_attimestampOptionalWhen it was voided.
void_reasonstringOptionalThe reason given on voiding.

Every transition is also written to the order log, readable at GET /api/v1/sales-orders/{id}/log.

Related