Track a Shipment¶

Shipments Movement data

Surface the live journey of any shipment by referencing the tracking ID, shipment ID, booking ID, or your custom booking ID. Each call returns the latest scan events, timestamps, and delivery ETA.

Verb

GET

Data freshness

Events stream in near real time

Retry guidance

Use exponential backoff when polling

Endpoint¶

GET Authenticated

URL: {{base_url}}/partner/shipment/track-shipment/{{identifier}}

Query Parameters¶

Parameter	Type	Required	Description
`extraDetails`	boolean	No	Set to `true` to include additional shipment details. Default: `false`

Identifier Options¶

You can track using any of these identifiers:

Identifier	When to use	Example
`trackingId`	Most common; shared with customers via labels and emails.	`692986D4`
`shipmentId`	Internal AAJ GUID used when you already have the shipment payload.	`bf214001-b3bb-4d49-a433-e5ef5177a732`
`bookingId`	Use when you only captured the commerce booking identifier.	`bf214001-b3bb-4d49-a433-e5ef5177a732`

Required Headers¶

Header	Value
`Authorization`	`Bearer {{ token }}`

cURL Example¶

curl -X GET "https://booking.aajexpress.org/api/v2/partner/shipment/track-shipment/692986D4?extraDetails=false" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response¶

{
  "success": true,
  "message": "Shipment tracked successfully",
  "data": {
    "carrier": "AAJ",
    "serviceType": "",
    "trackingNumber": "692986D4",
    "customBookingId": "FAV123456",
    "events": [
      {
        "meta": {
          "hub": null,
          "hubId": null,
          "status": 0,
          "location": "Online Branch",
          "userName": "Faith Philz"
        },
        "user": "68d51bf76d726a7296c52dbf",
        "bagTag": "",
        "category": "",
        "dateTime": "2025-11-28T12:26:25.000000+01:00",
        "exception": null,
        "scanType": "LABEL_CREATED",
        "description": "Label documents have been created",
        "manifestId": "",
        "objectType": "SHIPMENT",
        "shipmentTrackingId": "692986D4",
        "additionalInfo": null,
        "_id": "692986e163136da39a6af133",
        "createdAt": "2025-11-28T11:26:25.775Z",
        "updatedAt": "2025-11-28T11:26:25.775Z"
      }
    ],
    "status": 0,
    "timestamp": "2025-11-28T11:26:25.777Z",
    "description": "Label documents have been created",
    "weight": 90,
    "packageDimension": {
      "length": 32,
      "width": 25,
      "height": 2,
      "unit": "KGS",
      "dimensionalWeight": 0.32,
      "actualWeight": 90
    },
    "labelCreated": "2025-11-28T11:26:25.777Z",
    "eta": {
      "numberOfDays": 3,
      "dateOfArrival": "2025-12-01T11:26:12.000000+01:00",
      "lastTrack": "2025-11-28T11:26:12.843Z"
    },
    "senderLocation": {
      "city": "iKEJA",
      "state": "LA",
      "country": "Nigeria",
      "countryCode": "NG",
      "postcode": "23949",
      "location": "location"
    },
    "receiverLocation": {
      "city": "Ikeja",
      "state": "LA",
      "country": "Nigeria",
      "countryCode": "NG",
      "postcode": "23994",
      "location": "location"
    },
    "shipmentTrackingId": "692986D4",
    "bookingSearchId": "09130967",
    "searchedBy": "692986D4",
    "acknowledgementCopy": null
  }
}

Response Fields¶

Field	Description
`trackingNumber`	The public-facing tracking value printed on labels.
`customBookingId`	Your custom reference ID (if provided during booking creation).
`carrier`	The carrier handling the shipment (e.g., `AAJ`).
`events`	Chronological list of scan milestones with metadata about hub, user, and scan type.
`status`	Integer status that maps to the shipment lifecycle (see table below).
`timestamp`	When the shipment was last updated in the network.
`description`	Human-readable summary of the latest state.
`weight`	Total weight of the shipment in the configured unit.
`packageDimension`	Declared dimension + chargeable weight for billing reconciliation.
`labelCreated`	Timestamp when the shipping label was generated.
`eta`	Promise window, including arrival estimate and last update date.
`senderLocation` / `receiverLocation`	Sanitized address data for sender and receiver contacts.
`shipmentTrackingId`	The unique shipment tracking identifier.
`bookingSearchId`	Alternative search ID linked to the original booking.
`searchedBy`	The identifier used to perform this tracking lookup.

Shipment Status Codes¶

Status	Description
`0`	Label Created
`1`	Picked Up / Received
`2`	In Transit
`3`	Out for Delivery
`4`	Delivered

For complete status information, see Shipment Statuses.

Event Scan Types¶

Scan Type	Description
`LABEL_CREATED`	Shipping label has been generated
`PICKED_UP`	Package picked up from sender
`IN_TRANSIT`	Package in transit to destination
`OUT_FOR_DELIVERY`	Package out for final delivery
`DELIVERED`	Package successfully delivered
`EXCEPTION`	Delivery exception occurred

Real-time Notifications

For real-time customer notifications, poll until status reaches 4 (delivered), then confirm proof-of-delivery via the Single Shipment endpoint.