📦 wholesale
Wholesale Orders
Wholesale Orders is the main order-management screen for the Wholesale variant — a shared component (FnbWholesaleOrdersPage) also used by the Restaurant/Bakery variant's wholesale module. It has two tabs: Orders (create, track and bill B2B orders through a DRAFT → CONFIRMED → DISPATCHED → DELIVERED pipeline) and Customers (manage wholesale trade accounts with discount %, payment terms and credit limits).
📍 Menu path: Wholesale → Wholesale Orders
👤 Who uses it: All roles with the Billing feature enabled
Overview
The Orders tab lists every wholesale order with status filter chips, and each row expands to show line items, notes and delivery route.
The Customers tab is a separate, dedicated "Wholesale Customer" record (businessName, discount %, payment terms, credit limit, credit hold) — this is not the same table as the general POS Customers list.
Order status advances one step at a time via a button on each row (DRAFT → CONFIRMED → DISPATCHED → DELIVERED); there is no button to cancel an order from this screen even though CANCELLED is a valid status value used elsewhere in the API.
An order can be sent to the billing screen ("Bill via POS") to turn it into an actual sale/invoice — once that happens the row shows a Print Invoice icon instead.
This page is shared code (pos-react-lib), so some behavior (e.g. an internal navigation return-path) is written for the Bakery/Restaurant "wholesale-orders" route and does not always match the Wholesale variant's own routing — see Troubleshooting.
Before You Start
- You must have the Billing feature enabled on your plan.
Step-by-Step Guide
1 Create a new wholesale order
- Open Wholesale → Wholesale Orders (Orders tab) and click "+ New Order".
- Search and select a customer by name (this searches your regular Customers database, not the Wholesale Customers tab — see Troubleshooting), set Order Date, Delivery Date, Delivery Route/Zone and Payment Method.
- Add one or more items via the product search — each line has Qty, Unit, Retail price and Wholesale price; the order subtotal is Wholesale price × Qty summed across lines.
- Click "Create Order". The server auto-calculates GST (CGST/SGST or IGST) using the tax master for any line item that has a matched productId, and rejects the order if it violates a matched wholesale customer's credit hold, minimum order value or credit limit (see Troubleshooting for when these checks do and don't apply).
2 Advance an order and collect payment
- On the Orders tab, click the status button on a row (e.g. "Dispatched") to move it to the next status — DRAFT → CONFIRMED → DISPATCHED → DELIVERED.
- If Balance is greater than zero, click the payment icon to open Record Payment, enter an Amount (capped at the balance due) and a Payment Method, then click Record.
- The Balance column turns into a green "Paid" badge once balanceDue reaches (or is within 0.01 of) zero.
3 Turn an order into an invoice
- Click the invoice icon ("Bill via POS") on an order that has not yet been invoiced (no saleId) — this opens the billing screen pre-loaded with the order's items, customer and a note showing the order number and balance due.
- Complete the sale in the billing screen as usual.
- Back on Wholesale Orders, that order's row now shows a Print icon instead of the Bill icon — clicking it loads and displays the full invoice for the linked sale.
4 Manage wholesale customer accounts
- Switch to the Customers tab and click "+ Add Customer" to create a Wholesale Customer record: Business/Org Name (required), Contact Person, Phone, Email, Tax Number, Address, Discount %, Payment Terms (PREPAID/NET7/NET15/NET30/NET60), Credit Limit and Notes.
- Click Edit on a customer card to update these fields, or Delete to remove the account.
- Discount % set here is applied automatically to a new order's subtotal only when the order is linked to this Wholesale Customer record by ID — see Troubleshooting for why that link is often missing when orders are created from this page.
5 Review and edit an existing order
- Click anywhere on an order row to expand it and see its line items, notes and delivery route.
- Click the Edit (pencil) icon to reopen the order in the same modal used for creating orders and change delivery date/route, payment method or items, then click Update.
- Click Delete to permanently remove an order and its line items — there is no confirmation of a linked sale, so deleting an already-invoiced order does not affect or delete the sale record it was billed to.
Every Field & Button, Explained
| Field / Button | What it does |
|---|---|
Order # | Order number generated by the server (or "# |
Customer | The customerName captured on the order at creation time; free text, not a live link back to a Wholesale Customer record unless one was matched at creation. |
Order Date / Delivery | Order Date is required at creation; Delivery is optional and shown as "—" when not set. |
Total | subtotal − discountAmount + taxAmount, computed server-side at creation time. |
Balance | totalAmount − paidAmount; shows in red until it reaches ~0, then shows a green "Paid" badge. |
Status | DRAFT, CONFIRMED, DISPATCHED, DELIVERED or CANCELLED. The row button only ever advances one step forward through the first four; CANCELLED is never set from this UI. |
Status advance button | Shown only when a next status exists (i.e. not on DELIVERED or CANCELLED orders); calls PATCH /wholesale/orders/:id/status. |
Payment icon (hand-holding-coin) | Only shown when balance due > 0.01; opens Record Payment. The amount field is capped at the current balance due — you cannot overpay through this dialog. |
Bill via POS / Print Invoice icon | Bill via POS (invoice icon) shows only while the order has no linked sale; once billed it is replaced by a Print icon that opens the full invoice for that sale. |
Edit / Delete icons | Edit reopens the order form (New Order modal reused in edit mode); Delete removes the order and its items immediately after a browser confirm prompt — no undo. |
Items editor (in New/Edit Order modal) | Product search field, Qty, Unit, Retail price and Wholesale price per line; a line turns amber with a warning if its quantity is below the minimum order quantity found in an active Price List entry for that product. |
Customer card: Discount %, Terms, Credit limit | From the Wholesale Customer record; Discount % and Credit limit are only meaningful once an order is actually linked to this specific record (see Troubleshooting). |
Customer card status badge | ACTIVE by default; there is no button on this page to change status or set credit hold — those fields exist on the record (updateWholesaleCustomer supports creditHold/creditHoldReason/status) but are not exposed in this form. |
Tips & Best Practices
- When selecting a customer for a new order, type the exact same name as an existing Wholesale Customer's Business/Org Name if you want that account's discount/credit-limit checks to actually apply — see Troubleshooting.
- Use the status filter chips above the order list to quickly find, e.g., all DISPATCHED orders that still need a "Notify customer" message sent (only shown when the order has a contact phone — which this screen currently never records, see Troubleshooting).
- Deleting an order does not touch any sale it was already billed to — if you need to undo an invoiced wholesale order, cancel/refund the sale itself from Sales, not from here.
Troubleshooting & FAQ
I set a Credit Limit / Credit Hold / Minimum Order Value on a Wholesale Customer, but a new order for that customer went through anyway.
The New Order form's customer field searches your regular Customers list (via the generic customer search), not the Wholesale Customers tab, and the order payload it sends only contains a generic customerId/customerName — it never sends wholesaleCustomerId. On the server, createWholesaleOrder only runs the credit-hold, minimum-order-value and credit-limit checks when wholesaleCustomerId is present, so orders created from this screen skip all three checks unless something else in your workflow explicitly supplies wholesaleCustomerId. The client-side warning you may see (a confirm dialog about exceeding credit limit) only fires as a best-effort match when the selected customer's name happens to exactly equal a Wholesale Customer's Business/Org Name — it is not a guarantee.
I edited an order and its tax breakdown (CGST/SGST/IGST) is now wrong or unchanged.
Editing an order (updateWholesaleOrder) recalculates subtotal and totalAmount from the new items but does not recalculate tax at all — cgst/sgst/igst/cess and taxAmount are left exactly as they were computed at order creation. If you change items materially on edit, the tax figures on the order will no longer match the new items.
I edited an order that had a customer discount applied, and the discount disappeared from the total.
The Edit Order form has no discount field, so on save the client sends no discountAmount. The server treats a missing discountAmount as 0 on update (unlike creation, where it falls back to the matched customer's discountPercent) — so editing items on an order effectively removes any discount that was applied when it was first created.
The "Notify customer" share button never appears on a DISPATCHED order even though I want to text the customer.
It is gated on both status === DISPATCHED and order.contactPhone being set — but nothing in this page's New/Edit Order form or the underlying createWholesaleOrder function ever stores a contactPhone on the order record, so that condition is never true from orders created here. Use the Customers tab or Sales/Customer messaging tools instead.
After billing an order via "Bill via POS", the app tried to navigate somewhere unexpected on return.
This page is shared code also used by the Bakery/Restaurant variant's wholesale module, and the "Bill via POS" action hardcodes returnPath: '/bakery/wholesale-orders' regardless of which variant is running it. On pos-app-wholesale the equivalent route is /wholesale/orders, so any code relying on that return path will point at the wrong URL in this variant.
Can I cancel an order from this screen?
No — the status button only ever advances forward through DRAFT → CONFIRMED → DISPATCHED → DELIVERED. CANCELLED is a valid value accepted by the status API and used as a filter option elsewhere in the module, but there is no control on this page that sets it.