List Bookings

Bookings Read Only

Retrieve a paginated list of all bookings with full details including sender, receiver, packages, and pricing. Use this endpoint to populate booking dashboards and reconciliation reports.

Pagination

Use page and pageSize query params

Auth

Bearer token required

Use cases

Dashboards · Reports · Reconciliation

---

Endpoint overview

GET Authenticated

URL: {{base_url}}/employee/booking/list-bookings?page=1&pageSize=10&sourcePlatform

• Requires a valid bearer token in the Authorization header.
• Returns paginated booking results sorted by creation date descending.
• No request body required.

---

Required headers

Header	Value
Authorization	Bearer {{token}}

---

Query parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
pageSize	number	No	Results per page (default: 10, max: 100)
sourcePlatform	string	No	Filter by source platform (e.g., AAJ-Send)

---

Sample request

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

---

Response

{
  "success": true,
  "data": [
    {
      "_id": "69090bfcabc57c5eb35b0f15",
      "new": false,
      "sourcePlatform": "AAJ-Send",
      "senderHasNoNigerianAddress": false,
      "receiver": {
        "contact": {
          "name": "Rebecca Owolabi",
          "phone": "+442030484377",
          "email": "o.rebecca@gmail.com"
        },
        "addressDetails": {
          "addressLine1": "Flat 3, 14 Oakwood Drive, Leeds, LS11 OAA, United Kingdom.",
          "apartmentNumber": "",
          "city": "Leeds",
          "state": "West Yorkshire",
          "country": "United Kingdom",
          "stateOrProvinceCode": "WE",
          "countryCode": "GB",
          "postalCode": "BD11 1ND",
          "landmark": "",
          "streetLines": [
            "Flat 3, 14 Oakwood Drive, Leeds, LS11 OAA, United Kingdom."
          ]
        }
      },
      "sender": {
        "contact": {
          "owner": "68d3c8bede43d381d3b53dbb",
          "name": "Lanre Ogundele",
          "phone": "+2348036415243",
          "email": "lanre.o@gmail.com"
        },
        "addressDetails": {
          "addressLine1": "40, Landmark Street, Eleyele, Oyo.",
          "apartmentNumber": "",
          "city": "Ibadan",
          "state": "Oyo",
          "country": "Nigeria",
          "countryCode": "NG",
          "stateOrProvinceCode": "OY",
          "postalCode": "202102",
          "landmark": "",
          "streetLines": ["40, Landmark Street, Eleyele, Oyo."]
        }
      },
      "packageInsurance": "NE",
      "packages": {
        "packages": [
          {
            "actualWeight": 25,
            "packageDimension": {
              "length": 32,
              "width": 25,
              "height": 2,
              "weight": 0.32,
              "price": 0,
              "_id": "69090bfcabc57c5eb35b0f17",
              "createdAt": "2025-11-03T20:09:32.056Z",
              "updatedAt": "2025-11-03T20:09:32.056Z"
            },
            "predefinedDimension": "68fb3fa3bec965665202eacf",
            "items": [
              {
                "quantity": 1,
                "price": 20000,
                "hsCode": "62152000",
                "name": "Bow tie",
                "id": null,
                "excludePackingList": false,
                "_id": "69090bfcabc57c5eb35b0f18",
                "createdAt": "2025-11-03T20:09:32.057Z",
                "updatedAt": "2025-11-03T20:09:32.057Z"
              }
            ],
            "_id": "69090bfcabc57c5eb35b0f16",
            "createdAt": "2025-11-03T20:09:32.057Z",
            "updatedAt": "2025-11-03T20:09:32.057Z",
            "multiple": 1
          }
        ],
        "itemsValue": 20000,
        "packageType": "regular",
        "createMultiple": false,
        "type": "regular",
        "addOns": [],
        "items": []
      },
      "weight": 25,
      "addOns": [],
      "collectionMode": {
        "collectionType": "PICKUP",
        "pickupDetails": {
          "pickupDate": "2025-11-05T00:00:00.000Z",
          "pickupTimeRange": {
            "from": "9:00 AM",
            "to": "4:00 PM"
          }
        }
      },
      "customerAcceptanceState": 0,
      "branchName": "Gbagada Phase 1",
      "servedBy": "Olabanji Olaleye",
      "generatedBy": "68d3c8bede43d381d3b53dbb",
      "shipmentRate": "CR",
      "orderState": 1,
      "bookingState": 1,
      "partner": false,
      "numberOfPackages": 1,
      "subTotal": 6500,
      "totalAmount": 6988,
      "promoCode": "",
      "description": "Shipment Booking",
      "paid": true,
      "deliveryType": "DROP_OFF",
      "deliveryMode": "DOOR_STEP",
      "category": "68c2a70190f1fdaabd8c0b8e",
      "shipaOrEcommerce": false,
      "insuredValue": 0,
      "payments": {
        "transaction": {
          "method": "",
          "generateTransaction": "",
          "allowAsynchronousTransaction": false
        },
        "accountNumber": "",
        "customerId": ""
      },
      "serviceType": "AIR_EXPORT",
      "carrier": "AAJ",
      "courier": {
        "rateId": "1^11",
        "token": "DPD TWO DAY",
        "rateIds": []
      },
      "getAcknowledgementCopy": false,
      "bookingDate": "2025-11-03T20:09:32.054Z",
      "collectionEvents": [],
      "createdAt": "2025-11-03T20:09:32.057Z",
      "updatedAt": "2025-11-06T08:15:08.703Z",
      "type": "IN",
      "location": "United Kingdom",
      "packageValueClaim": 20000,
      "searchId": "72285500",
      "__v": 0,
      "extraCharges": {
        "fuelSurcharge": {
          "value": 0,
          "type": "percentage",
          "amount": 0
        },
        "onShippingFee": 6500,
        "packagingFee": {
          "value": 0,
          "type": "price",
          "amount": 0
        }
      },
      "source": {
        "oid": "67f7c951ad794273b8519f8a",
        "name": "AAJ Express",
        "branch": "",
        "accountNumber": "747801"
      },
      "hasDispatch": null,
      "shipmentId": null,
      "bookingVat": 487.5,
      "bookingInsurance": {
        "type": "NE",
        "fee": 0
      }
    }
  ],
  "pagination": {
    "total": 626,
    "page": 1,
    "pageSize": 10,
    "totalPages": 63
  },
  "status": 200,
  "message": "Bookings fetched successfully with VAT and insurance details.",
  "timestamp": "2025-11-09T20:36:26.936Z"
}

---

Key response fields

Field	Type	Description
success	boolean	Indicates whether the request was successful
data	array	Array of booking objects
data[]._id	string	Unique booking identifier
data[].searchId	string	Short search-friendly ID for quick lookups
data[].sourcePlatform	string	Platform where booking originated (e.g., AAJ-Send)
data[].receiver	object	Receiver contact and address details
data[].sender	object	Sender contact and address details
data[].packages	object	Package details with weight, dimensions, items
data[].weight	number	Total weight of all packages
data[].numberOfPackages	number	Count of packages in this booking
data[].collectionMode	object	Collection type and pickup details
data[].bookingState	number	State code. See Booking Enums
data[].orderState	number	Order state code. See Booking Enums
data[].subTotal	number	Subtotal before taxes (in NGN)
data[].totalAmount	number	Total amount including VAT and fees
data[].paid	boolean	Whether payment has been completed
data[].deliveryType	string	DROP_OFF or PICKUP
data[].deliveryMode	string	DOOR_STEP or TERMINAL
data[].serviceType	string	Service type (e.g., AIR_EXPORT)
data[].carrier	string	Carrier code (e.g., AAJ, DHL)
data[].branchName	string	Branch handling the booking
data[].servedBy	string	Staff member who handled the booking
data[].bookingDate	string	ISO timestamp when booking was created
data[].bookingVat	number	VAT amount for the booking
data[].bookingInsurance	object	Insurance type and fee
data[].extraCharges	object	Breakdown of fuel surcharge, packaging fees, etc.
data[].source	object	Source organization details
pagination	object	Pagination metadata
pagination.total	number	Total number of bookings
pagination.page	number	Current page number
pagination.pageSize	number	Results per page
pagination.totalPages	number	Total number of pages
status	number	HTTP status code (200 for success)
message	string	Response message
timestamp	string	ISO timestamp of the response

---

Error responses

Unauthorized

{
  "success": false,
  "status": 401,
  "message": "Invalid or expired token",
  "timestamp": "2025-11-09T20:36:26.936Z"
}

---

Tip: Use pagination.totalPages to iterate through all results. For large datasets, consider using webhooks or the Fetch Recent Bookings endpoint for incremental updates.