Sale Orders
A sale order is a customer's order for one or more law-book Full Sets or individual monthly parts. This page explains the order's 12-state lifecycle and the two things Head Office can do to it from this console today: approve it for despatch, or cancel it.
Sale orders are captured in the Sales-Executive field app or the public API — a field executive visits a customer, builds the order, and it flows up into this console already drafted. There is no New sale order button anywhere in /staff, and the console has no create, edit or view page for orders — only a list with two row actions. The HO console's job is to review and act on orders that already exist, not to originate them.
Where to find it
Open Sales → Sale Orders in the left navigation. The link only appears if your role holds sale_order.view (or you are a super administrator).
The state machine
Every sale order sits in exactly one of 12 states. Most of the journey — from the moment a Sales Executive starts an order to the moment it is queued for Head Office — happens in the field app / API, with no console involvement. The console becomes relevant the instant an order reaches SubmittedToHo, and again at any point if the order needs to be stopped with Cancel.
State legend
| State | What it means | Who moves it here |
|---|---|---|
| Draft | The order has just been started; lines can still be freely changed. | Field app / API |
| LinesConfirmed | The customer's line items — which Full Sets or parts, and quantities — are locked in. | Field app / API |
| PaymentPending | The order is waiting for the customer's payment to be recorded and allocated before it can move on. | Field app / API |
| CreditPending | The order is being sold on credit and is waiting on a credit-limit / credit-request approval. | Field app / API |
| DiscountPending | A discount applied to the order needs approval before the order can proceed. | Field app / API |
| ReadyForHo | All financial clearance (payment, credit or discount, whichever applied) is done; the order is queued to be sent up to Head Office. | Field app / API |
| SubmittedToHo | The order has reached Head Office and is waiting for a decision. This is the only state from which HO Approve is offered. | Field app / API (arrives here) |
| ApprovedForDespatch | Head Office has approved the order; it is now eligible for stock reservation and picking. | Console — HO Approve |
| InDespatch | Stock for the order has been picked and packed, and the package is on its way to the customer. | Outside console (despatch process) |
| Completed | The order has finished its despatch cycle. The terminal, successful state. | Outside console (despatch process) |
| Suspended | A held/paused state defined on the model. No action in this console currently sets or clears it. | Not exposed anywhere found |
| Cancelled | The order was cancelled. Terminal — nothing can move an order out of this state. | Console — Cancel (or field app/API) |
Drafting an order, confirming its lines, clearing payment/credit/discount, and submitting it to HO all happen in the field app or the public API — there is no console screen for any of them today. Likewise, the final leg from ApprovedForDespatch through InDespatch to Completed is not driven by any Sale Order button here; it progresses as despatch work happens elsewhere (see Picking Waves and Packages). The console's role is deliberately narrow: review an order once it reaches Head Office, and be able to stop it at any point.
What the console exposes
The Sale Orders list has exactly two row actions. Both are gated by permission and by the order's current state, and both re-check those rules on the server even if you click faster than the screen refreshes.
HO Approve
Moves an order from SubmittedToHo to ApprovedForDespatch — the moment Head Office signs off on an order so it can be reserved and picked.
- Visible when: the order's state is SubmittedToHo and you hold sale_order.approve (or are a super administrator).
- Confirmation: yes — a confirmation dialog, no form fields.
- Icon / colour: a check-badge icon, success (green).
- Find the order
On the Sale Orders list, use the Filters panel's State filter and select SubmittedToHo to see everything waiting on your decision.
- Select HO Approve on the order's row
The button only appears on rows currently in SubmittedToHo — you won't see it on any other order.
- Confirm
A dialog asks you to confirm. There is nothing else to fill in.
- Check the result
On success the row's State column updates to ApprovedForDespatch and the order becomes eligible to be picked into a wave.
Cancel
Stops an order dead, moving it to Cancelled from whatever state it is currently in.
- Visible when: the order's state is anything other than Completed or Cancelled and you hold sale_order.cancel (or are a super administrator).
- Confirmation: yes, plus a required form field.
- Icon / colour: an x-circle icon, danger (red).
| Field | Type | Required | Notes |
|---|---|---|---|
reason | Textarea | Yes | Max 500 characters. The action will not proceed with this left blank. |
- Select Cancel on the order's row
Available on any order not already Completed or Cancelled — including orders still in early field-app-driven states.
- Type a reason
Be specific — this text is the permanent record of why the order was stopped, and is what a colleague (or an auditor) will read later. Up to 500 characters.
- Confirm
Select the confirming button in the dialog.
- Check the result
The row's State updates to Cancelled. This is terminal — there is no console action to bring a cancelled order back.
Because Cancel is offered from almost every state — including ones the field app manages, like Draft or PaymentPending — it is Head Office's universal "stop this order" switch, independent of how far along it is. Use it when an order should not proceed at all, not as a substitute for the earlier, field-app-driven stages this console doesn't expose.
The list
Sale Orders opens straight on its list — there is no create page (orders are placed from the field app), but each row can be opened to a read-only detail view (below). Rows sort by created_at descending by default.
| Column | Shows |
|---|---|
reference | The order's reference number, as a badge. Searchable and sortable. |
| Customer | The ordering customer's full name (via their profile). |
| Salesperson | The full name of the staff member credited with the order. |
state | The order's current lifecycle state, as a coloured badge (see the state legend above). |
total_net_amount | The order's net value, formatted as Indian Rupees. Sortable. |
order_date | The date the order was placed. Sortable. |
Filter
The Filters panel offers a single State drop-down listing all 12 states, so you can, for example, isolate everything sitting in SubmittedToHo waiting on your approval, or everything already Cancelled for an audit trail.
Viewing an order Built
Use the View row action (or click through) to open an order's detail page — read-only, gated by the same sale_order.view permission as the list. It has two parts:
- Order — an information panel with the reference, the current state (same coloured badge as the list), the customer and salesperson, the order type, the order date and any state reason.
- Amounts — the order's gross, discount, tax and (in bold) net totals, in Rupees.
- Line items — a table of every line on the order: product code and name, quantity, unit price, the discount and tax breakdown, and each line's gross and net amount.
- Payments applied — a read-only table of the payment allocations posted against this order: the voucher, the line it was applied to, and the amount (plus gateway charges and any allocation discount).
- Credit requests / Discount requests — the credit and discount approval requests raised on this order: the amount, the request state, the reason, who raised it, and who approved it (with the decision date and remarks).
- State history — the full audit trail of the order's state changes: from-state, to-state, the reason, who performed the transition and when.
Everything here is read-only — an order is driven through its lifecycle by the HO Approve / Cancel actions and by the field app, not edited as a form. The lines you see are also what the sales reports aggregate; the payments, credit/discount requests and state history tables let you trace an order's full financial and approval history without leaving the page.
Visibility scoping — you may not see every order
Unlike a flat permission check, the Sale Orders list also filters which rows you can see, on top of whether the module is visible to you at all:
- Full visibility — you see every sale order in the system — applies if you are a super administrator or hold sale_order.view_all.
- Scoped visibility — everyone else only sees an order if either:
- the order's customer falls within your geography scope or your customer scope (the same scoping used across the console — see Customers), or
- you are recorded as the order's salesperson.
If a colleague mentions an order you cannot find, it is almost always this scoping at work rather than a fault: the order's customer sits outside the region or customer scope assigned to you, and you are not its salesperson. An administrator with sale_order.view_all, or a super administrator, can always see it and can review or widen your geography/customer scope if that access is genuinely needed.
See also
- Customers — the customer record each sale order belongs to, and how geography/customer scoping is set up.
- Payment Vouchers — how a customer's payment is recorded and allocated against an order, feeding the PaymentPending stage.
- Discounts, Refunds & Charges — the approval flow behind DiscountPending, and what happens after an order is billed.
- Picking Waves — how an ApprovedForDespatch order's stock is actually picked, packed and despatched.
- Schedulers — the background jobs that quietly drive some of the "outside console" transitions shown in the diagram above.