Shipment Statuses & Scan Types

Reference Shipments

This page documents all shipment status codes, scan types, and their descriptions. Use this reference to interpret tracking events and shipment lifecycle states returned by the API.

---

Shipment Statuses

Every shipment has a numeric status field. Map these codes to understand the current state of a shipment.

Code	Label	Description
0	Pending	Shipment created, awaiting processing
1	Received	Shipment received at origin hub
2	In Transit	Shipment is moving between hubs
3	Out For Delivery	Shipment is on the way to the recipient
4	Delivered	Shipment has been delivered successfully
5	Exception	An issue occurred (damaged, lost, held, etc.)
6	Available For Pickup by Customer	Shipment is at destination, ready for pickup
7	Voided	Shipment has been cancelled/voided
8	Returned	Shipment is being returned to sender
9	Undergoing Clearance	Shipment is in customs clearance
10	Ready for Export	Shipment cleared and ready for export
11	Departed	Shipment has departed from origin country
12	Reweighed	Shipment has been reweighed (weight updated)

---

Scan Types

Scan types represent specific events in the shipment lifecycle. Each tracking event includes a scanType field.

Scan Type	Status Code	Description
PICKUP_SCAN	0	Shipment has been picked up by rider
ORIGIN_SCAN	1	Shipment received at the origin hub or warehouse
ARRIVAL_SCAN	2	Shipment arrived at a hub, facility, or transit location
DEPARTURE_SCAN	11	Shipment departed from a hub for the next leg of transit
OUTBOUND_SCAN	3	Shipment is on the way to be delivered
DELIVERY_SCAN	4	Shipment has been delivered
EXCEPTION_SCAN	5	Shipment encountered an issue (damaged, lost, held, etc.)
FINAL_DESTINATION_SCAN	6	Shipment is available for pickup by customer
RETURN_SCAN	8	Shipment is being returned
CLEARANCE_SCAN	9	Shipment is undergoing or has completed clearance
EXPORT_SCAN	10	Shipment has been exported out of the origin country
REWEIGH_SCAN	12	Shipment has been reweighed (new weight recorded)

---

Scan Type Descriptions

Detailed explanations for each scan type event.

{
  "ORIGIN_SCAN": "Shipment has been received at the origin hub or warehouse",
  "ARRIVAL_SCAN": "Shipment has arrived at a hub, facility, or transit location",
  "DEPARTURE_SCAN": "Shipment has departed from a hub or facility for the next leg of transit",
  "OUTBOUND_SCAN": "Shipment is on the way to be delivered",
  "FINAL_DESTINATION_SCAN": "Shipment is available for pickup by customer",
  "PICKUP_SCAN": "Shipment has been picked up by rider",
  "DELIVERY_SCAN": "Shipment has been delivered",
  "EXCEPTION_SCAN": "Shipment encountered an issue or delay (damaged, lost, held, or other exception)",
  "CLEARANCE_SCAN": "Shipment is undergoing or has been cleared",
  "RETURN_SCAN": "Shipment is being returned",
  "EXPORT_SCAN": "Shipment has been exported out of the origin country",
  "REWEIGH_SCAN": "Shipment has been reweighed"
}

---

Status-to-Scan Mapping

Use this to understand which scan types correspond to which status codes.

Status Code	Status Label	Triggering Scan Types
0	Pending	LABEL_CREATED (initial state)
1	Received	ORIGIN_SCAN
2	In Transit	ARRIVAL_SCAN, DEPARTURE_SCAN
3	Out For Delivery	OUTBOUND_SCAN
4	Delivered	DELIVERY_SCAN
5	Exception	EXCEPTION_SCAN
6	Available For Pickup by Customer	FINAL_DESTINATION_SCAN, PICKUP_SCAN
7	Voided	Manual void action
8	Returned	RETURN_SCAN
9	Undergoing Clearance	CLEARANCE_SCAN
10	Ready for Export	EXPORT_SCAN
11	Departed	DEPARTURE_SCAN (international)
12	Reweighed	REWEIGH_SCAN

---

Example Tracking Event

Here's a sample tracking event object from the API:

{
  "meta": {
    "hub": "68cac248c81b722a507c1273",
    "location": "Lagos",
    "userName": "John Doe",
    "coordinates": {
      "latitude": 6.5244,
      "longitude": 3.3792
    }
  },
  "_id": "692e9b5832a429dd519b48a0",
  "scanType": "ORIGIN_SCAN",
  "objectType": "SHIPMENT",
  "shipmentTrackingId": "691AFA42",
  "dateTime": "2025-11-17T11:16:25.513Z",
  "description": "Received in good condition",
  "hub": "68cac248c81b722a507c1273",
  "additionalInfo": "",
  "category": "EXPRESS_CENTRE",
  "user": "68a47b9a2fc46e7e78da0ad8"
}

---

Tip: Subscribe to webhooks to receive real-time notifications when shipment statuses change, rather than polling the API.