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

ColumnShows
package_numberThe package's identifying number, shown as a badge. Searchable and sortable.
Customercustomer.profile.full_name — who the package is addressed to.
Carriercarrier.name — the delivery carrier handling this package.
tracking_numberThe carrier's tracking reference. Searchable.
StateA coloured badge — see the diagram above for the colour key.
Despatched / Delivered New 2026-11-11When 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_codA tick/cross icon — whether this is a Cash on Delivery (COD) package (see below).
cod_receivedA 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

FilterWhat it narrows
StateAll 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_codA three-way yes / no / all toggle to isolate Cash on Delivery packages from ordinary ones.
Screenshot placeholderThe Packages list showing Package Number, Customer, Carrier, Tracking Number, State, and the two COD icon columns, with the State and is_cod filter panel open.

Actions

Permissions

Print label needs only package.view. Every other action below — including the bulk Mark delivered and the Import deliveries button — needs package.track as well.

  1. 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.

  2. 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.

  3. 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_cost automatically (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".

  4. 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.

  5. 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:

    FieldTypeRequiredNotes
    delivery_stateSelect — Delivered / Returned / LostYesThe 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_at New 2026-11-07Date and time — defaults to nowNoWhen 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_reasonTextareaNoFree text — typically filled in when recording a Returned outcome, but the form does not enforce this.
    delivery_notesTextareaNoAny additional context about the delivery attempt.
  6. 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_received to 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).

Recording the last delivery completes the sale order for you

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:

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.

ColumnWhat it means
MoveThe stock move's reference (MOV-…). Searchable.
ProductThe product being shipped. Searchable.
In this packageHow much of that move is in this parcel.
Move totalHow 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 stateThe stock move's own state badge — see Stock Moves.
A package can hold part of a move — and a move can be split across packages

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.

Bulk actions

  1. 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.

  2. 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 .csv file (up to 5 MB). The first row is the header. Columns:

    ColumnRequiredNotes
    tracking_number or package_numberOne of themHow the row finds its package — by tracking number first, then by package number.
    statusYesdelivered, returned or lost.
    dateNoDelivery (or return) date. Write it day first, dd/mm/yyyy — 05/11/2026 is 5 November. 2026-11-05 also works. Blank means now. Not used on a lost row.
    notesNoSaved 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 carrier

    Every 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 status column, 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 & pathPermissionPurpose
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

Both pieces of evidence are required — not either/or

When Record delivery is used to mark a package Delivered and its carrier's type is hand_delivery, the transition is blocked with 422 unless both are already on file: a tracking log with event_type = delivered for that package, and a package attachment with category = delivery_challan. Courier / India Post / transport packages are unaffected — this rule only applies to the hand-delivery carrier type.

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 statusAllowed afterNotes
Picked upnothing yet (package must be despatched)Agent collected it from the warehouse.
In transitPicked up, or Not delivered (retry)On the way to the customer.
DeliveredIn transitNeeds a photo of the signed delivery challan; the package becomes Delivered with the agent as delivered by.
Not deliveredIn transitNeeds 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).

Proof is preserved once a package reaches a terminal state (US-INV-67)

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.