Retrieve all shipments

Shipments Read only

List every shipment visible to your token, including metadata about sender, receiver, package contents, and fulfillment state. Use this feed to populate dashboards or reconcile downstream tools.

Pagination

Use page and pageSize query params

Auth

Bearer token required

Use cases

Ops dashboards · Billing audits · SLA tracking

Endpoint overview

GET Authenticated

URL: {{base_url}}/employee/shipment/list-shipments

• Requires a valid bearer token.
• Returns a paginated array of shipments sorted by createdAt descending.
• Supports query parameters such as page and pageSize.

Required headers

Header	Value
Authorization	Bearer {{token}}

Sample request

GET /employee/shipment/list-shipments?page=1&pageSize=10 HTTP/1.1
Host: {{ base_url }}
Authorization: Bearer {{ token }}
Accept: application/json

Response payload

{
  "success": true,
  "data": [
    {
      "_id": "692986d463136da39a6af12f",
      "booking": {
        "receiver": {
          "contact": {
            "name": "Amos Obaide",
            "phone": "+23490387845890",
            "email": "amos_@yopmail.com"
          },
          "addressDetails": {
            "addressLine1": "3 jesus estate",
            "addressLine2": "3 jesus estate",
            "city": "Ikeja",
            "state": "Lagos",
            "country": "Nigeria",
            "stateOrProvinceCode": "LA",
            "countryCode": "NG",
            "postalCode": "23994",
            "landmark": "landmark",
            "location": "location",
            "streetLines": []
          }
        },
        "sender": {
          "contact": {
            "name": "Enohense Idemudia",
            "phone": "+23409038845894",
            "email": "sandra_@yopmail.com"
          },
          "addressDetails": {
            "addressLine1": "Maryland LAGOS",
            "addressLine2": "Maryland LAGOS",
            "city": "iKEJA",
            "state": "Lagos",
            "country": "Nigeria",
            "countryCode": "NG",
            "stateOrProvinceCode": "LA",
            "postalCode": "23949",
            "landmark": "iKORODU",
            "location": "location",
            "streetLines": []
          }
        },
        "packages": {
          "packages": [
            {
              "actualWeight": 90,
              "packageDimension": {
                "length": 32,
                "width": 25,
                "height": 2,
                "weight": 0.32,
                "price": 0
              },
              "items": [
                {
                  "quantity": 3,
                  "price": 0,
                  "manufacturerCountry": "NG",
                  "unitMeasurement": "CON",
                  "name": "Bagss",
                  "excludePackingList": false
                }
              ],
              "multiple": 1
            }
          ],
          "itemsValue": 30000,
          "createMultiple": false,
          "packageType": "regular",
          "type": "regular",
          "addOns": [],
          "items": []
        },
        "_id": "692944f5c489fb616853e1da",
        "sourcePlatform": "AAJ-Send",
        "totalAmount": 98715,
        "deliveryType": "DROP_OFF",
        "deliveryMode": "DOOR_STEP",
        "searchId": "09130967",
        "humanizedName": "BKG692944f5c489fb616853e1da",
        "bookingStatus": "UNKNOWN",
        "numberOfItems": 3
      },
      "shipmentType": "DOMESTIC",
      "trackingId": "692986D4",
      "invoice": "",
      "shipmentTrackingNumber": "",
      "trackingUrl": "",
      "labelDocuments": [
        {
          "carrier": "AAJ",
          "url": "https://aaj-media-bucket.s3.us-east-1.amazonaws.com/labels/9d010be0/692986D4_AAJ_label.pdf"
        }
      ],
      "currentTrackingUpdates": "",
      "voidState": false,
      "status": 0,
      "inManifest": false,
      "manifestId": "",
      "eta": {
        "numberOfDays": 3,
        "dateOfArrival": "2025-12-01T11:26:12.000000+01:00",
        "lastTrack": "2025-11-28T11:26:12.843Z"
      },
      "shipmentServiceType": "",
      "carrier": "AAJ",
      "items": [
        {
          "name": "Bagss",
          "quantity": 3,
          "price": 0,
          "unitMeasurement": "CON",
          "hsCode": "",
          "manufacturerCountry": "NG",
          "excludePackingList": false
        }
      ],
      "dimension": {
        "length": 32,
        "width": 25,
        "height": 2,
        "unit": "KGS",
        "dimensionalWeight": 0.32,
        "actualWeight": 90
      },
      "mps": false,
      "childShipments": [],
      "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"
        }
      ],
      "source": {
        "id": "68d51bf76d726a7296c52dbd",
        "name": "Favs Inc",
        "account_number": "558162",
        "branch": "",
        "customer_id": ""
      },
      "createdAt": "2025-11-28T11:26:25.777Z",
      "updatedAt": "2025-11-28T11:26:25.777Z",
      "declaredValue": 0,
      "receiver": {
        "contact": {
          "name": "Amos Obaide",
          "phone": "+23490387845890",
          "email": "amos_@yopmail.com"
        },
        "addressDetails": {
          "addressLine1": "3 jesus estate",
          "city": "Ikeja",
          "state": "Lagos",
          "country": "Nigeria",
          "countryCode": "NG",
          "postalCode": "23994"
        }
      },
      "weight": 90,
      "chargeableWeight": 0,
      "deliveryMode": "DOOR_STEP",
      "sender": {
        "contact": {
          "name": "Enohense Idemudia",
          "phone": "+23409038845894",
          "email": "sandra_@yopmail.com"
        },
        "addressDetails": {
          "addressLine1": "Maryland LAGOS",
          "city": "iKEJA",
          "state": "Lagos",
          "country": "Nigeria",
          "countryCode": "NG",
          "postalCode": "23949"
        }
      },
      "humanStatus": "Pending",
      "meta": {
        "totalPrice": 98715,
        "packageType": "regular",
        "booking": "692944f5c489fb616853e1da",
        "origin": ["Nigeria", "LA"],
        "destination": ["Nigeria", "LA"],
        "receiverName": "Amos Obaide",
        "senderName": "Enohense Idemudia",
        "carrier": "AAJ",
        "deliveryType": "DROP_OFF",
        "deliveryMode": "DOOR_STEP"
      },
      "id": "692986d463136da39a6af12f"
    }
  ],
  "pagination": {
    "total": 64,
    "page": 1,
    "pageSize": 10,
    "totalPages": 7
  },
  "status": 200,
  "message": "Shipments fetched successfully.",
  "timestamp": "2025-12-02T07:55:04.659Z"
}

Key fields

Field	Type	Description
_id	string	Unique shipment identifier (MongoDB ObjectId).
trackingId	string	Short, human-readable tracking code (e.g., 692986D4).
status	number	Current status code. See Shipment Statuses for mapping.
humanStatus	string	Human-readable status label (e.g., Pending, Delivered).
carrier	string	Carrier code (AAJ, DHL, UPS, etc.).
shipmentType	string	DOMESTIC or INTERNATIONAL.
sender	object	Sender contact and address details.
receiver	object	Receiver contact and address details.
items	array	List of package items with name, quantity, price, etc.
dimension	object	Package dimensions (length, width, height, weight).
eta	object	Estimated time of arrival with numberOfDays and dateOfArrival.
events	array	Tracking event history with scan types and timestamps.
labelDocuments	array	URLs to generated shipping labels.
booking	object	Embedded booking details (sender, receiver, packages).
pagination	object	Pagination metadata: total, page, pageSize, totalPages.

Tip: Use pagination.totalPages to iterate through all results. For real-time updates, consider webhooks instead of polling.