Packages
A package is one physical parcel — the unit that actually gets sealed, handed to a carrier, and tracked to delivery. This page tracks every package's journey and lets you record what happens to it after it leaves the warehouse.
Where packages come from
Packages are created as part of picking-wave preparation (packing a wave's stock moves into physical parcels) — there is no create button here. Since November 2026 they are built for you: the nightly auto-wave run generates the packages for every wave it creates, and the Generate packages button on a wave's page (see Picking Waves) builds any that are missing. Each package goes to one customer at one shipping address — two orders from the same customer going to two different addresses get two parcels — and carries that address and the goods value of what is inside. Most packages reach Despatched in bulk, the moment their wave is despatched — see the cascade explained on the Picking Waves page. This page is where you track each package individually from that point on, and seal it beforehand.
Stock transfer and purchase-order packages New 2026-11-11 are made from the transfer's or PO's own page instead: Generate packages builds them as Draft while the document is in Packaging, and each one is shipped on its own (Ship on the document's Packages tab, or Ship all) — only then do its contents leave the sender. They are received or reported missing package by package from that same tab, and the document's state follows its packages. A package always belongs to exactly one wave, transfer or purchase order. See Stock Transfers and Purchase Orders.
Where to find it & who can see it
Open Despatch › Packages in the left navigation. The list is visible to anyone holding package.view (or a super administrator). There is no create form; a package's tracking number, box and shipping address are changed with Edit details (below). Each row has a View action showing the package's Contents and its GPS tracking trail (both described below), plus its other row actions.
The package lifecycle
A package can be in one of nine states. Only four transitions are driven from this screen; getting to Despatched normally happens automatically when its wave is despatched.
Columns
| Column | Shows |
|---|---|
package_number | The package's identifying number, shown as a badge. Searchable and sortable. |
| Customer | customer.profile.full_name — who the package is addressed to. |
| Carrier | carrier.name — the delivery carrier handling this package. |
tracking_number | The carrier's tracking reference. Searchable. |
| State | A coloured badge — see the diagram above for the colour key. |
| Despatched / Delivered New 2026-11-11 | When the package left with its wave (or was shipped with its transfer / purchase order) and when it was delivered. Sortable; hide or show them from the column toggle. |
is_cod | A tick/cross icon — whether this is a Cash on Delivery (COD) package (see below). |
cod_received | A tick/cross icon — whether the COD cash-on-delivery amount for this package has been confirmed received. |
The list defaults to newest first (created_at desc).
Filters
| Filter | What it narrows |
|---|---|
| State | All nine PackageState values: Draft, Packing, Sealed, Labeled, Despatched, Delivered, Returned, Lost, Cancelled. Filtering on Sealed is how you find packages that are closed up but whose label has not been recorded yet. |
| is_cod | A three-way yes / no / all toggle to isolate Cash on Delivery packages from ordinary ones. |
Actions
- Print label New 2026-11-07
On every row and at the top of a package's detail page. Opens this package's barcode address label in a new tab; its menu offers Carrier default, Continuous 4×5 in (dot-matrix), Thermal 4×6 in and A4 sheet. Printing a label changes nothing on the package — use Mark labelled to record it. To print a whole wave at once use Print labels on Picking Waves, which also explains what a label shows.
- Edit details New 2026-11-07
Opens a small form with the package's Tracking number, Box type and Shipping address. Use it to type in or correct the carrier's tracking (AWB) number, or to swap the box or the delivery address before the parcel leaves.
- The tracking number can be changed until the package is delivered, returned or lost. Clearing the field removes it.
- The box and address can only be changed before despatch — after that they are greyed out. The box list shows only the carrier's active boxes; the address list shows only this customer's addresses.
- Changing the box or address of a package that is already Sealed or Labeled recalculates its postage.
To enter tracking numbers for a whole wave in one go, use Enter tracking numbers on the wave's page — see Picking Waves.
- Seal — Draft or Packing → Sealed Confirmation required
Use this once a package is physically packed and ready to be closed up. Confirming calculates and stores the package's
postage_costautomatically (via the postage calculator, based on weight/carrier/destination) — you do not enter a postage figure yourself. If the carrier has a minimum quantity per package, a package holding fewer items is refused: "{carrier} requires at least N items per package". - Mark labelled — Sealed → Labeled Confirmation required
Records that the package's address label has been printed and applied. Only appears on a package currently Sealed. It changes nothing else — no postage is recalculated and no stock is touched.
This step is optional. Despatching a wave sweeps up every one of its packages that has not already been delivered, returned, lost or cancelled — whether or not it was marked labelled. Use it when you want the labelling step on the record, and use the State filter on Sealed to see which packages are still waiting on a label.
- Record delivery — Despatched → Delivered, Returned or Lost
Only appears once a package is Despatched. Unlike most actions in this console, it opens a form directly rather than a plain confirmation dialog:
Field Type Required Notes delivery_stateSelect — Delivered / Returned / Lost Yes The outcome you are recording; the package's state moves to whichever you choose. Delivered closes the package's stock moves: any move whose every part is now delivered (or returned/lost and re-sent) moves to Done. A move split across several packages waits until the last of them is settled. Returned and Lost re-send the contents automatically — see When a package comes back or is lost. Recording the last delivery completes the sale order — see below. delivered_atNew 2026-11-07Date and time — defaults to now No When the parcel was delivered (used when the outcome is Delivered). It cannot be in the future, and cannot be earlier than the day the package was despatched. Your name is recorded as the person who entered the delivery. return_reasonTextarea No Free text — typically filled in when recording a Returned outcome, but the form does not enforce this. delivery_notesTextarea No Any additional context about the delivery attempt. - Mark COD received Confirmation required
Only shown when the package is COD and has not yet been marked received. It does not change the package's state — it simply sets
cod_receivedto true, recording that the cash the carrier collected on delivery has come back to AIR (usually because it was reconciled through a payment lot — see below).
An order is complete when its books have been delivered — not when they were despatched. When you record a package's outcome, the portal checks the parent sale order: if that was the last outstanding delivery on it — every delivery move for the order, including any re-send of a returned or lost parcel, is now either Done or Cancelled — the order moves itself from In Despatch to Completed. Nobody has to close it by hand, and the change is written to the order's own state log with your name against it, exactly as a manual completion would be.
Anything still outstanding holds the order open — a move that is still Reserved, Shipped or Suspended all count as outstanding. So an order with a held part stays In Despatch until that part is either despatched and delivered or cancelled. If an order you expected to close is still sitting in In Despatch, look for its unfinished moves on Stock Moves.
How packages and boxes are chosen Updated 2026-11-11
When a wave's packages are generated, its moves are grouped (by customer and shipping address, or by product category for a by-product wave), cut by the wave's max moves per package, the carrier's maximum quantity per package and maximum weight per package, and the heaviest box the carrier has — whichever limit is lowest — packed in the old order (urgent orders first, then state, district, town, PIN code and customer name), and then each group is fitted into boxes using the books' dimensions as well as their weight:
- The group goes into the smallest box by volume (then by sort order) of the carrier's active box types that takes it: the contents' weight within the box's maximum weight, the contents' volume within the box volume × the packing efficiency (system setting
despatch.packing_efficiency_pct, 85% by default — see System Config), and every book fitting inside the box in some orientation. - Max fit: every package is filled up to the carrier's limits (books and weight) before the next one is started, and an order line is split across packages to do so. For example, with a limit of 10 books, lines of 6, 4, 3 and 15 books pack as 10 + 10 + 8: the 3 and the first 7 of the 15 share the second package. A carrier with a maximum of 1 sends one book per package.
- If no single box takes the group, it is split automatically into several packages — largest items first, each into the first package with room. When a line doesn't fit an open package whole, that package is topped up with as many of its books as still fit, and the rest go on. Each package gets the smallest box that fits it.
- The packages generated are a suggestion: they stay Draft until sealed. A line too big by size for every box is split too, into as many books as the roomiest box holds. Only a single book that fits no box at all gets a package of its own with no box, to be sorted out by hand.
- Every book needs its weight, height, width and length on the product. Books missing any of them are not packed — they wait on the wave, and the generate step names the products so you can fill them in and generate again. If no book on the wave has full measurements, generating is refused.
- A carrier with no active box types gets no packages: generating is refused with "Carrier … has no active box types; link one to it before packing wave …", and the nightly run records the same and leaves the wave unpacked. A wave with no items is refused the same way.
What is inside a package Built
Open a package row's View action and the first tab is Contents — the list of stock moves packed into that parcel. It needs only package.view, the same permission as the list itself. It is read-only: contents are written when the wave's packages are generated (see Picking Waves), never edited here.
| Column | What it means |
|---|---|
| Move | The stock move's reference (MOV-…). Searchable. |
| Product | The product being shipped. Searchable. |
| In this package | How much of that move is in this parcel. |
| Move total | How much the move authorises altogether. When it is larger than In this package, the row is annotated Partially packed — the difference has not been packed yet, and is either in another package or still waiting to be packed. |
| Move state | The stock move's own state badge — see Stock Moves. |
A stock move used to live in exactly one package. It no longer does: a move can be split, so that part of it ships now and the rest ships later, in a different parcel with its own tracking number. That is why In this package and Move total are two separate columns.
In practice, package generation still packs whole moves today, so the two figures will normally match — nothing yet decides to pack a part-quantity automatically. The machinery for a split shipment is in place; what is not in place is anything that chooses to make one on its own.
When a move is split, each parcel decrements only the stock it actually carries at despatch, and the move is only marked Shipped once all of it has gone. The unshipped remainder stays reserved.
Understanding COD
Cash on Delivery (COD) means the customer pays for the goods in cash at the point of delivery — to the postman on an India Post despatch, or to the courier rider — rather than in advance. AIR uses it for certain despatches. A COD package therefore carries a cash liability until that money is actually banked and confirmed — which is why is_cod and cod_received are separate flags, and why Mark COD received exists independently of the delivery outcome itself. The cash from many COD packages is banked together and reconciled in batches — see COD Payment Lots for how that reconciliation works, and note that Mark COD received here can also happen automatically as part of a lot's Reconcile step.
How a package becomes COD (November 2026). It is worked out automatically from what is packed: a package holding any copy from a COD order is marked COD, and its COD amount — what the carrier collects — is the value of those copies (their share of the order line), less any part of that line already paid. It updates whenever the package's contents change, and is frozen once the package is in a COD payment lot or its COD is marked received. The COD amount is printed in a heavy box on the package label.
When a package comes back or is lost New 2026-11-07
Recording Returned or Lost no longer leaves the order stuck. For every order line the package carried, the portal creates a replacement stock move for the same quantity, to the same customer and with the same carrier, and leaves it Confirmed. From there it follows the normal nightly path: the 02:00 run reserves it (all the usual checks apply — for example a return flagged suspend further parts holds it), the 03:00 run puts it on a new wave and builds its package, and you despatch it as usual.
- The original stock moves are closed as Done. On Stock Moves the Replaces and Replaced by columns link the two, and each move's history says which package was returned or lost.
- The sale order stays In Despatch until the replacement is delivered, then completes on its own.
- A re-sent copy is not billed or counted twice — reports and payment checks treat it as the same part.
- Stock is not put back by this flag. Books that physically come back are restocked (or written off as damaged) through the return-shipment process, after inspection. A lost parcel's stock already left at despatch.
- Nothing is re-sent for an order that has been cancelled.
Bulk actions
- Mark delivered New 2026-11-07
Tick the packages, then choose Bulk actions › Mark delivered and enter one Delivered at date for all of them. Each package is recorded on its own exactly as Record delivery would: any that can't be marked — not despatched yet, a hand delivery without its GPS and challan proof, or a date before the despatch day — are skipped, and a warning lists them with the reason. The rest are saved.
- Import deliveries (CSV) New 2026-11-07
The Import deliveries button at the top of the list takes a carrier's delivery report as a
.csvfile (up to 5 MB). The first row is the header. Columns:Column Required Notes tracking_numberorpackage_numberOne of them How the row finds its package — by tracking number first, then by package number. statusYes delivered,returnedorlost.dateNo Delivery (or return) date. Write it day first, dd/mm/yyyy—05/11/2026is 5 November.2026-11-05also works. Blank means now. Not used on alostrow.notesNo Saved as the delivery notes, or as the return reason for a returned row. tracking_number,package_number,status,date,notes EK123456789IN,,delivered,05/11/2026,Signed by receptionist ,PKG-2026-00042,returned,06/11/2026,Addressee moved EK987654321IN,,lost,,Not traced by carrierEvery row is applied on its own, with the same checks as Record delivery. Rows that can't be applied — no matching package, an unknown status, a package already in that state, a hand delivery without proof, a date out of range — are skipped, and the result lists them by row number with the reason. A file without a
statuscolumn, without either reference column, or with no data rows is refused as a whole.
Delivery tracking (GPS) & hand-delivery proof Built
Every despatched package can accumulate a trail of GPS-stamped tracking events — captured by the SE (or hand-delivery carrier) in the field via the Flutter app, not typed in here. The HO console shows this trail read-only: open a package row's View action to see the GPS tracking trail relation manager. It requires delivery_tracking.view — a package.view-only user sees the package but not this tab.
API — recording and reading the trail
| Method & path | Permission | Purpose |
|---|---|---|
POST /api/v1/delivery-tracking-logs |
delivery_tracking.create | Record one GPS event. Body: package_id, event_type (pickup / in_transit / attempted / delivered / returned), latitude (-90..90), longitude (-180..180), optional accuracy_meters, device_info, notes. captured_by and captured_at are set server-side from the authenticated actor and the current time — they cannot be supplied by the client. Returns 201 with the created log. Rejected with 422 if the package is Draft or Cancelled — events can only be logged for a despatchable package. |
GET /api/v1/packages/{package}/tracking-logs |
delivery_tracking.view | Lists a package's tracking logs oldest-first (captured_at ascending), each with the capturing user eager-loaded. This is the same data the HO relation manager renders (sorted the same way). |
The hand-delivery completion rule
Recording a hand delivery at the office New 2026-11-11
When the agent delivered but couldn't report it from the field app (no phone, no signal, app not yet rolled out), staff with package.office_delivery (included in the built-in Staff role) use Record hand delivery (office) — on a despatched hand-delivery package's row or at the top of its page. Upload the signed delivery challan (photo or PDF — required), set when it was delivered, and say why it is recorded at the office. The package becomes Delivered with you as delivered by; its GPS tracking trail shows a Delivered event with no coordinates, device office entry, and your note — so an office-recorded delivery is always distinguishable from one confirmed by GPS. The challan is kept as the package's delivery-challan attachment. The rule above still applies to everything else: Record delivery keeps refusing a hand delivery without the agent's GPS event and challan.
Delivery agents New 2026-11-12
A hand-delivery package can be given to an in-house delivery agent — any staff user. Use the row action Assign delivery agent, or tick several packages and use Bulk actions › Assign delivery agent (needs package.track; non-hand-delivery and already-closed packages are skipped and listed). Leave the agent empty to unassign. The Delivery agent and Agent status columns and the Delivery agent filter show who carries what. One package already holds every order for one customer and address, so an agent delivering several packages delivers several orders at once.
The agent reports progress from the field app (role needs package.deliver). Each report is a GPS-stamped tracking event; the package stays Despatched until delivered:
| Agent status | Allowed after | Notes |
|---|---|---|
| Picked up | nothing yet (package must be despatched) | Agent collected it from the warehouse. |
| In transit | Picked up, or Not delivered (retry) | On the way to the customer. |
| Delivered | In transit | Needs a photo of the signed delivery challan; the package becomes Delivered with the agent as delivered by. |
| Not delivered | In transit | Needs a reason. The agent can try again, or HO records Returned with Record delivery. |
API: GET /api/v1/me/deliveries (my packages still out for delivery, with customer, address, sale orders and status; ?open=0 for all), POST /api/v1/me/deliveries/{package}/status (event_type = pickup | in_transit | delivered | attempted, plus latitude, longitude, notes, and challan file for delivered), and for HO PATCH /api/v1/packages/{package}/delivery-agent and GET /api/v1/packages?delivery_agent_id=.
Automatic delivery after N days (November 2026). If the package's carrier has Auto-deliver after (days) set, the 04:00 package auto-delivery job marks it Delivered that many days after it was despatched, unless a carrier complaint or a return is open on it. Hand-delivery packages are never delivered this way. You can still record any outcome yourself before then — if you mark it Lost or Returned, or open a complaint, while the job is running, your outcome wins and the job leaves the package alone.
delivered_at (whether defaulted to "now" or entered on Record delivery, Mark delivered or in an import file) can be neither in the future nor earlier than the day the package was despatched — otherwise the delivery is refused (422).
A package attachment can no longer be deleted once its package is Delivered, Returned, or Lost — DELETE /api/v1/packages/{package}/attachments/{attachment} returns 422 for a package in any of these three states. This locks the delivery-challan (and any other) evidence in place permanently once the delivery outcome is settled; attachments can still be freely added or removed while the package is in an earlier state.
Related pages
See Picking Waves for how packages reach Despatched in bulk, COD Payment Lots for how COD cash collected on delivery is banked and reconciled, and Attachments for the delivery-challan / proof-of-delivery upload API referenced above.