Chapter 1 — Why This Combo Exists
If you handle freight that arrives by air, you need to track it from before it lands all the way through receiving, storage, and (if applicable) onward fulfillment.
Air Cargo OS gives you the tracking. Warehouse OS gives you the receiving and storage operations. Together they form the ground-handling workflow.
Chapter 2 — Roles in This Combo
| Role | What's different |
|---|---|
| company_admin | Configures AWB provider env vars + warehouse setup. |
| operations_manager | Monitors AWB queue + ground-side receiving in one workflow. |
| operator | Receives air cargo against AWB-linked pre-alerts. |
| customer_service | Answers customer questions using AWB status + inventory together. |
| customer_aircargo (portal) | Sees their AWBs and (if they have inventory rights) their stock once received. |
Chapter 3 — AWB-Linked Pre-Alert Flow
An AWB is the carrier's tracking. A pre-alert is the warehouse's "expect this." Linking them creates one continuous record.
Recommended workflow
- Customer (or freight forwarder) gives you the AWB number.
- Look up the AWB at /console/business/ground-ops/awb-check.
- If status = booked / in_transit / arrived — good, the AWB is real.
- Create a pre-alert at /console/ops-manager/pre-alert.
- In the pre-alert form, link to the AWB record (set
awb_doc_id). - The pre-alert now has both the carrier-side tracking and the warehouse-side expected-line list.
linked_prealert_id on the AWB record. This is what makes the AWB visible to the customer through their portal — without it, the AWB looks orphan to the customer.
Chapter 4 — Ground-Side Receiving from an AWB
When the cargo physically arrives, ground operations receives it just like any other inbound — but with AWB context.
- The AWB status flips to arrived or available_for_pickup (provider event).
- Ground ops driver picks up cargo from the airline.
- Operator opens the linked pre-alert at /console/operator/receiving.
- Receives line by line, capturing lot/serial/expiry as required.
- Trenvar creates handling units tagged with both the customer (owner) and the AWB ID for traceability.
- Storage accrual begins.
- The AWB status (still managed by the carrier) eventually moves to delivered; the linked pre-alert moves to received.
Chapter 5 — AWB Events Feeding Storage Accrual
Air Cargo OS unlocks storage screens. The AWB workflow drives the start of the storage clock.
The "received at" timestamp on a handling unit is what storage accrual uses as the start point. So:
- If receiving happens promptly after AWB arrived, the storage clock starts on the right day.
- If there's a delay between AWB landing and receiving, storage starts at receiving — not landing.
- Customers sometimes negotiate "free days" to absorb minor delays — set
freeDayson the storage rule.
Chapter 6 — Customer-Facing Visibility
Customers with the customer_aircargo role see their AWBs. With added portal roles, they can see their inventory too.
| Role combo | What customer sees |
|---|---|
| customer_aircargo only | Only AWB status (events, origin, destination, flight). Not inventory. |
| customer_aircargo + customer_user | AWB status + inventory + invoices + payments. The standard "freight customer" portal experience. |
What the customer sees in their portal
- AWB lookup — pre-arrival status, in-flight tracking, arrival, delivery.
- Inventory (with customer_user) — once received, their stock appears here.
- Invoices — storage charges that started accruing from receipt.
Chapter 7 — Common Pitfalls
"Customer can't see their AWB"
- The AWB has no
linked_prealert_idorcustomer_id— link it. - The customer is missing the
customer_aircargorole. - The AWB is genuinely under a different customer.
"AWB status is stale"
- Pull mode cache is 15 minutes — wait or hit Check again.
- Live provider returned an error — check audit log for the call.
- Push-mode webhook hasn't fired — check provider's outbound integration config.
"Storage accrued before goods arrived"
- The receiving event was posted on the wrong day. Use a manual storage adjustment to credit the over-accrual.
- Add freeDays to the storage rule for future receipts.
"AWB shows delivered but inventory isn't received"
- The carrier's "delivered" event happened (cargo released to ground handler) but no one created a receiving event in Trenvar yet.
- Operator needs to receive at /console/operator/receiving against the linked pre-alert.
Chapter 8 — Full Worked Example: AWB to Inventory in 5 Days
An air cargo shipment from carrier booking through ground handling to in-warehouse stock, in a Warehouse + Air Cargo tenant.
Day -1 (Sun) — pre-arrival
- Customer Acme emails: "AWB 160-12345678 booked, ETA Tuesday".
- You (ops manager) open
/console/business/ground-ops/awb-check. Type "160-12345678". Click Check. - Carrier returns: status=booked, origin=HKG, destination=YVR, flight=CX838 ETD Mon 23:00 HKT.
- AWB record created. You click Link to Customer → "Acme Corp".
Day 0 (Mon) — pre-alert created
- You go to
/console/ops-manager/pre-alert. Create Pre-Alert. - Customer = Acme. Source = air_cargo. AWB Reference = 160-12345678 (typeahead picks the record).
- Add expected lines: 200 units of SKU-A, 150 units of SKU-B. Save.
- The pre-alert and AWB are now linked both directions.
Day 1 (Tue) — in transit
- Carrier's webhook fires when CX838 departs HKG. AWB status → in_transit. Event timeline updates.
- Acme's customer_aircargo user logs in to portal, looks up AWB, sees "In Transit" with the departure event.
Day 2 (Wed) — arrived
- Webhook: status → arrived at YVR cargo terminal at 06:30 local.
- You see the change in /console/business/ground-ops/awb-check.
- Send a runner to the airline's cargo terminal to collect the cargo.
Day 2 (Wed) afternoon — receiving
- Cargo arrives at your warehouse dock.
- Operator opens
/console/operator/receiving, picks Acme's pre-alert (the one linked to the AWB). - Receives line by line: 200 units SKU-A, 150 units SKU-B. Both lines accept clean.
- Trenvar creates 2 handling units tagged owner_customer_id=Acme. Storage accrual starts.
- Pre-alert status → received. AWB linked_prealert_id remains for future audit.
Day 3 (Thu) — webhook closes the AWB
- Carrier sends final webhook: status → delivered.
- The AWB and pre-alert are both fully traceable from origin (HKG) → flight → arrival → receiving → bins.
- Acme's portal user sees full timeline.
Days 4+ — storage + outbound
- Storage accrual runs daily charging Acme $0.05/unit/day for the 350 units.
- Outbound orders ship from this stock as Acme places them.
From AWB booked to in-warehouse stock with full traceability — 5 days, no manual reconciliation.
Appendix A — Glossary (Combo-Specific)
Cross-cutting terms specific to Warehouse + Air Cargo. For per-OS terms, see the Warehouse OS and Air Cargo OS guides' glossaries.
AWB-linked pre-alert — A warehouse pre-alert with an AWB reference set, so receiving and air carrier tracking are connected. Drives customer portal visibility.
Ground-side receiving — Operator workflow at the warehouse for cargo that just arrived from an airport. Same as standard receiving but typically against an AWB-linked pre-alert.
Linked AWB — An AWB record with linked_prealert_id or linked_shipment_ref set. Without a link, the AWB is "orphan" and not surfaced anywhere except AWB Lookup.
Receipt timestamp — When the warehouse accepts goods at the dock. This (not the AWB "delivered" event) is when storage accrual starts.
End of Warehouse + Air Cargo Combo Guide · v1.0 · May 2026