📋 garment

Advance Orders

Advance Orders lets you book a customer's order for garment stock that has not arrived yet — capturing the customer, the specific size/colour items wanted, and an advance deposit — then tracks the order through Pending, Arrived, Fulfilled or Cancelled.

📍 Menu path: /garment/advance-orders

👤 Who uses it: Owner,Manager,Staff

Overview

Each order has a customer half (Customer Name, Phone, with type-ahead search against your Customers list) and an items half — a repeatable grid of Product, Size, Colour, Qty and unit price, plus an Expected Arrival Date, an Advance Paid amount, and Notes.

Saving an order auto-generates a sequential order number in the form ADV-0001, ADV-0002, … by scanning existing orders for the highest numeric suffix and incrementing it.

Total Amount is computed automatically from the items grid (unit price × quantity per line, summed) both live in the form and again server-side on save — it is never entered directly.

Orders move through four statuses: PENDING (booked, stock not yet arrived), ARRIVED (stock is in, ready to notify/collect), FULFILLED (handed to the customer), and CANCELLED. One-tap "Arrived" and "Fulfilled" buttons appear directly on each order row at the appropriate stage.

Clicking an order row expands it in place to show its full item list (product, size/colour, quantity and line total) and any notes, without leaving the list.

Before You Start

The route requires the "billing" plan feature; there is no plan-tier gate.
Only Customer Name and at least one item with a Product name are required to save an order — Phone, Expected Arrival Date and Advance Paid can all be filled in later.
Product search in the item grid searches the live catalogue (GET /products), but items can also be typed freely without matching an existing product.

Step-by-Step Guide

1 Book a new advance order

Click New Order.
Type into Customer Name * (required) — matching customers appear in a dropdown; selecting one also fills Phone.
Set Expected Arrival Date and, if the customer is paying something upfront, Advance Paid.
Use the Search & Add Product box to find and add catalogue items, or type directly into the Items grid's Product/Size/Colour/Qty/price cells — click Add Item for more rows.
Review the live Total shown next to Add Item, then click Save Order.

2 Progress an order as stock arrives

When the stock for a PENDING order comes in, click the Arrived button directly on that order's row to mark it ARRIVED.
Once the customer has been contacted and picks up their order, click Fulfilled to close it out.
Use the edit icon at any stage to update customer details, items, or Advance Paid — this fully replaces the item list, so add back any items you want to keep alongside new ones.

3 Review and manage orders

Use the status chips (ALL, PENDING, ARRIVED, FULFILLED, CANCELLED) to filter the list, each showing a live count.
Click anywhere on an order row (outside the action buttons) to expand it and see its full item breakdown and notes.
Click the trash icon and confirm to permanently delete an order.

Every Field & Button, Explained

Field / Button	What it does
`New Order`	Opens the blank advance order form.
`Customer Name * / Phone`	Required customer name (with type-ahead search) and phone; picking a search result fills both.
`Expected Arrival Date`	The date the ordered stock is expected to arrive.
`Advance Paid`	Amount collected upfront as a deposit against the order.
`Search & Add Product`	Type-ahead search against the live product catalogue; selecting a result adds/fills an item row with its name, SKU and price.
`Items grid (Product, Size, Colour, Qty, unit price)`	One row per size/colour/product combination ordered; rows can be added or removed freely (at least one must remain).
`Total (form footer)`	Live sum of unit price × quantity across every item row.
`orderNumber`	Auto-generated sequential ID in the form ADV-0001, ADV-0002, … assigned once at order creation and never editable.
`Status`	PENDING, ARRIVED, FULFILLED or CANCELLED, shown as a colour-coded badge; PENDING starts indigo, ARRIVED amber, FULFILLED green, CANCELLED grey.
`Arrived button`	One-tap shortcut shown only on PENDING orders to move them to ARRIVED.
`Fulfilled button`	One-tap shortcut shown only on ARRIVED orders to move them to FULFILLED.
`Status filter chips`	ALL, PENDING, ARRIVED, FULFILLED, CANCELLED — each with a live count.
`Expand row`	Clicking an order row (outside its buttons) reveals its full item list and notes inline.
`Edit / Delete icons`	Edit opens the form pre-filled, including all items; Delete permanently removes the order after a confirmation prompt.

Tips & Best Practices

Collect at least a partial Advance Paid amount at booking time — it is stored on the order for your own reference, but nothing in this screen enforces or reminds you to collect it, so make it a habit rather than relying on the system.
Move orders to Arrived as soon as stock physically comes in, even before you have contacted the customer — it is the cue that separates "still waiting on the supplier" from "ready to call the customer".
Use the expand-row view to double check the exact size/colour breakdown before calling a customer about their order, rather than relying on memory.

Troubleshooting & FAQ

Will the customer be told automatically when I mark an order Arrived?

Yes — marking an order Arrived (PUT /garment/advance-orders/:id with status=ARRIVED) sends an SMS to the customer's phone if an SMS gateway is configured under Settings → Integrations. If no gateway is configured, or the order has no phone number on file, no message goes out and you should follow up manually.

I edited an order and some of its original items disappeared.

Saving an edit replaces the entire item list with whatever is currently in the Items grid at save time — if a row was removed (or never loaded) before you saved, it is gone. Re-add any items you want to keep alongside your changes before clicking Save Order.

Could two orders ever get the same order number?

Order numbers are computed by scanning all existing orders for the highest ADV-#### suffix and adding one, then re-checked against the live table immediately before saving — if a collision is detected (e.g. from two near-simultaneous creates), the number is recomputed and retried automatically up to a few times before the save fails with a "please retry" error, so a duplicate should not reach the database.

Is this the same as the Advance Booking / Lay-by feature on the generic Sales pages?

No — they are unrelated features that happen to share the word "advance". The generic Layby/Advance Booking page (Sales & Bills) is created from the point-of-sale screen for stock already in hand, tracks instalment payments down to a zero balance, and converts straight into an invoice; it also requires the Advanced plan tier. This garment Advance Orders page is for stock that has not arrived yet, has no instalment schedule or invoice-conversion step, and carries no plan-tier restriction.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/pos-app-garment/src/pages/garment/AdvanceOrderPage.jsx

Backend endpoints used:

GET /garment/advance-orders
POST /garment/advance-orders
GET /garment/advance-orders/:id
PUT /garment/advance-orders/:id
DELETE /garment/advance-orders/:id
GET /customers (search)
GET /products (search)

Related tables (db-core repositories):

GarmentAdvanceOrder (idx_GarmentAdvanceOrder_tenant on tenantId+status)
GarmentAdvanceOrderItem (idx_GarmentAdvanceOrderItem_order on advanceOrderId)

Redux slices:

None — local component state only

Feature flag key: billing

listAdvanceOrders and createAdvanceOrder in packages/pos-core/src/garment.js both carry comments explicitly noting a prior bug: the list endpoint originally did not attach each order's items, "which made the edit modal open with a blank items grid"; it now does a second query against GarmentAdvanceOrderItem batched by order id. updateAdvanceOrder fully deletes and re-inserts all items whenever the request includes an items array (which the edit modal always sends) — there is no per-item PATCH, so a partial item edit is really "replace the whole set". orderNumber generation reads every existing orderNumber, strips the "ADV-" prefix, parses the numeric suffix, computes the max + 1, then re-checks that candidate number against the live table immediately before insert and retries (up to 5 attempts) on a clash — there is still no DB-level unique constraint, so this is a best-effort mitigation rather than a hard guarantee under true concurrent load, but it closes the window that existed with a plain read-then-write. The garment.controller.js updateAdvanceOrder handler now sends an SMS (via the same sms_gateway integration and smsService.sendSms(...).catch(err => console.warn(...)) pattern used by garm-orders) when status transitions to ARRIVED and the order has a customer phone on file — matching the "auto-notify on arrival" copy on this page. If no SMS gateway is configured, or the order has no phone, nothing is sent and no error is shown, so staff should still follow up manually in that case.