Special Orders
Special Orders handles the case where a customer wants something you don't currently stock — you take their order, raise a supplier purchase order for it in one click, and the moment that PO is received the order flips to "Arrived" so you can tell the customer to come collect it.
Overview
The page has two sections: Waiting for supplier (pending customer orders you still need to buy in) and Arrived — tell the customer (orders whose linked supplier PO has been fully received).
Special Orders itself does not create sales orders — it reads the existing pending Sale Orders (created from Sale Orders directly, or by converting a quotation) and adds the "raise a PO for this" and "notify on arrival" actions on top.
Once a purchase order raised from this page is fully received, the linked sales order automatically moves from Waiting to Arrived — there is no manual "mark as arrived" step.
Before You Start
- Requires the
purchase_ordersfeature at the Advanced plan tier or above. - A customer order must already exist as a pending Sale Order (created directly, or converted from a Quotation) before it can appear under Waiting for supplier here.
- Raising the supplier PO (the "Order from supplier" action) is restricted server-side to Admin and Manager roles — other roles can view both lists and send the arrived-notification WhatsApp message, but cannot raise a PO themselves.
- At least one Supplier must already exist to be selectable in the PO dialog.
Step-by-Step Guide
1 Raise a supplier PO for a pending customer order
- Find the order under Waiting for supplier — it shows the order number, customer, expected date, pending quantity and value.
- Click Order from supplier (only shown if no PO has been raised for that order yet).
- Pick a supplier from the dropdown in the dialog — the PO is created using that order's pending product lines at their purchase cost.
- Click Raise PO. The row then shows "PO raised — waiting" until the goods are received, at which point it automatically shows "PO received" and the order moves to the Arrived section.
2 Notify a customer their special order has arrived
- Once an order appears under Arrived — tell the customer (goods received against its linked PO), click Order arrived on that row.
- This opens WhatsApp with a pre-filled "your order has arrived, please visit to collect it" message addressed to the customer's phone number.
- Fulfil the order as usual from the Sale Orders screen once the customer collects it — Special Orders itself does not process the pickup/fulfilment.
3 Keep the lists current
- Click Refresh at any time to re-pull both the Waiting and Arrived lists, e.g. right after receiving a purchase order elsewhere in the app.
Every Field & Button, Explained
| Field / Button | What it does |
|---|---|
Waiting for supplier section | Pending customer Sale Orders that still need a supplier PO raised (or whose PO has been raised but not yet received). |
Arrived — tell the customer section | Orders whose linked supplier PO has been fully received; only action available here is the WhatsApp arrival notification. |
Order from supplier button | Opens the supplier picker and, once a supplier is chosen and Raise PO is clicked, creates a purchase order from that sales order's pending lines at purchase cost. Restricted to Admin/Manager server-side. |
Supplier picker dropdown | Lists existing Suppliers to choose from when raising a PO; at least one supplier must exist. |
"PO raised — waiting" / "PO received" label | Replaces the Order from supplier button once a PO exists for that order, reflecting whether it has been received yet. |
Order arrived button | Opens WhatsApp with a pre-filled arrival message addressed to the customer's phone (if on file). |
Pending qty / Value columns | How many units are still outstanding on that order, and its total value, respectively. |
Refresh button | Re-fetches both the Waiting and Arrived lists immediately. |
Tips & Best Practices
- Raise the PO as soon as a special order comes in rather than batching them — the order only moves to Arrived automatically once its PO is fully received, so delaying the PO delays the whole cycle.
- Keep customer phone numbers on the underlying Sale Order accurate; the one-click arrival notification depends on it to address the WhatsApp message correctly.
- If a staff member without Admin/Manager rights needs to raise a PO for a special order, have a manager do it from this page rather than trying to work around it via Purchase Orders directly.
Troubleshooting & FAQ
The "Order from supplier" button is missing or fails when I click it.
I raised a PO but the order still shows "PO raised — waiting" days later.
No orders show under Waiting for supplier at all.
Why is Special Orders missing from my sidebar?
🧑💻 Developer Notes
Source component(s):
frontend-app/packages/pos-react-lib/src/pages/SpecialOrdersPage.jsx
Backend endpoints used:
GET /salesorders/pending (Waiting for supplier list)GET /salesorders/arrived (Arrived list)GET /suppliers?limit=200 (supplier picker)POST /salesorders/:id/create-po (raise PO from a sales order — server restricts to ADMIN/MANAGER roles)
Related tables (db-core repositories):
SalesOrderSalesOrderItemSalesOrderFulfillmentPurchaseOrder
Feature flag key: purchase_orders (requires advanced plan tier or above)
This page has no dedicated database table of its own — it is a workflow layer over the existing SalesOrder data (via backend/src/routes/salesorder.routes.js, mounted at /salesorders) plus the standard Purchase Order pipeline. The create-po route is guarded with authorize('ADMIN', 'MANAGER') middleware, so non-privileged roles can view and notify but the raise-PO action itself will 403 if attempted directly against the API.