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. 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.
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). It is index/view-only — no create or edit form. Each row has a View action showing the package's GPS tracking trail (see below), plus its other row actions.
The package lifecycle
A package can be in one of eight states. Only three 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. |
is_vpp | A tick/cross icon — whether this is a Value-Payable-Post (VPP) package (see below). |
vpp_received | A tick/cross icon — whether the VPP 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 eight PackageState values: Draft, Packing, Sealed, Despatched, Delivered, Returned, Lost, Cancelled. |
| is_vpp | A three-way yes / no / all toggle to isolate Value-Payable-Post packages from ordinary ones. |
Actions
- 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. - 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. 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 VPP received Confirmation required
Only shown when the package is VPP and has not yet been marked received. It does not change the package's state — it simply sets
vpp_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).
Understanding VPP
Value-Payable Post (VPP) is an India Post service where the customer pays for the goods in cash at the point of delivery, rather than in advance. AIR uses it for certain despatches. A VPP package therefore carries a cash liability until that money is actually banked and confirmed — which is why is_vpp and vpp_received are separate flags, and why Mark VPP received exists independently of the delivery outcome itself. The cash from many VPP packages is banked together and reconciled in batches — see VPP Payment Lots for how that reconciliation works, and note that Mark VPP received here can also happen automatically as part of a lot's Reconcile step.
Bulk actions
There are none — packages are actioned one row at a time.
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
delivered_at (whether defaulted to "now" or supplied explicitly on the Record delivery form) can no longer be a future timestamp — the request is rejected with 422 if it is after the current time.
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, VPP Payment Lots for how VPP cash collected on delivery is banked and reconciled, and Attachments for the delivery-challan / proof-of-delivery upload API referenced above.