Create Booking¶
Bookings
Write
Create a new shipment booking with sender/receiver details, package information, and delivery preferences. This is the primary endpoint for initiating shipping workflows in the AAJ Express system.
Returns
Booking object with quote
Auth
Bearer token required
Use cases
New shipments · Partner integrations · Bulk orders
Endpoint overview¶
POST
Authenticated
URL: {{base_url}}/employee/booking/create-booking/
- Requires a valid bearer token in the Authorization header.
- Returns the created booking object with calculated quote and pricing.
- Validates sender/receiver addresses and package dimensions.
Required headers¶
| Header | Value |
|---|---|
Authorization |
Bearer {{token}} |
Content-Type |
application/json |
Request body structure¶
| Field | Type | Required | Description |
|---|---|---|---|
receiver |
object |
Yes | Receiver contact and address details |
receiver.contact |
object |
Yes | Name, phone, and email of receiver |
receiver.addressDetails |
object |
Yes | Full address including city, state, country, postal code |
sender |
object |
Yes | Sender contact and address details |
sender.contact |
object |
Yes | Name, phone, and email of sender |
sender.addressDetails |
object |
Yes | Full address including city, state, country, postal code |
packages |
object |
Yes | Package details including weight, dimensions, and items |
packages.packages |
array |
Yes | Array of package objects with actualWeight, packageDimension, and items |
collectionMode |
object |
Yes | Collection type (PICKUP or DROP_OFF) and pickup details if applicable |
deliveryType |
string |
Yes | DROP_OFF or PICKUP - how package is delivered to receiver |
deliveryMode |
string |
Yes | DOOR_STEP or TERMINAL - final delivery method |
serviceType |
string |
Yes | Service type code (e.g., AIR_EXPORT, SEA_FREIGHT). See Booking Enums |
carrier |
string |
Yes | Carrier code (e.g., AAJ, DHL, UPS) |
shipmentRate |
string |
No | Rate type: SR (Standard) or CR (Custom). Default: CR |
packageInsurance |
string |
No | Insurance class. See Booking Enums for options |
Sample request¶
{
"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": ""
}
},
"sender": {
"contact": {
"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": ""
}
},
"packages": {
"packages": [
{
"actualWeight": 25,
"packageDimension": {
"length": 32,
"width": 25,
"height": 2,
"weight": 0.32
},
"predefinedDimension": "68fb3fa3bec965665202eacf",
"items": [
{
"quantity": 1,
"price": 20000,
"hsCode": "62152000",
"name": "Bow tie",
"id": "68c2d050dbcf02dd65903ed1",
"excludePackingList": false,
"category": "Clothing & Fabrics"
}
]
}
],
"itemsValue": 20000,
"packageType": "regular",
"type": "regular"
},
"collectionMode": {
"pickupDetails": {
"pickupTimeRange": {
"from": "9:00 AM",
"to": "4:00 PM"
},
"pickupDate": "2025-11-05T00:00:00.000Z"
},
"collectionType": "PICKUP"
},
"deliveryType": "DROP_OFF",
"deliveryMode": "DOOR_STEP",
"serviceType": "AIR_EXPORT",
"carrier": "AAJ",
"shipmentRate": "CR",
"packageInsurance": "NE"
}
Response¶
On successful creation, the API returns the complete booking object with the associated quote.
{
"success": true,
"data": {
"booking": {
"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": ""
}
},
"sender": {
"contact": {
"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": ""
}
},
"packages": {
"packages": [
{
"actualWeight": 25,
"packageDimension": {
"length": 32,
"width": 25,
"height": 2,
"weight": 0.32,
"price": 0,
"_id": "69090befabc57c5eb35b0f08",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z",
"id": "69090befabc57c5eb35b0f08"
},
"predefinedDimension": "68fb3fa3bec965665202eacf",
"items": [
{
"quantity": 1,
"price": 20000,
"hsCode": "62152000",
"name": "Bow tie",
"id": "68c2d050dbcf02dd65903ed1",
"excludePackingList": false,
"category": "Clothing & Fabrics",
"_id": "69090befabc57c5eb35b0f09",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z"
}
],
"_id": "69090befabc57c5eb35b0f07",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z",
"multiple": 1,
"id": "69090befabc57c5eb35b0f07"
}
],
"itemsValue": 20000,
"packageType": "regular",
"type": "regular",
"addOns": [],
"items": []
},
"collectionMode": {
"pickupDetails": {
"pickupTimeRange": {
"from": "9:00 AM",
"to": "4:00 PM"
},
"pickupDate": "2025-11-05T00:00:00.000Z"
},
"collectionType": "PICKUP"
},
"payments": {
"transaction": {
"method": "",
"generateTransaction": "",
"allowAsynchronousTransaction": false
},
"accountNumber": "",
"customerId": ""
},
"courier": {
"rateIds": []
},
"_id": "69090befabc57c5eb35b0f06",
"new": false,
"sourcePlatform": "AAJ-Send",
"senderHasNoNigerianAddress": false,
"packageInsurance": "NE",
"weight": 25,
"addOns": [],
"customerAcceptanceState": 0,
"shipmentRate": "CR",
"orderState": 5,
"bookingState": 1,
"partner": false,
"numberOfPackages": 1,
"subTotal": 6500,
"totalAmount": 6988,
"description": "Shipment Booking",
"paid": false,
"deliveryType": "DROP_OFF",
"deliveryMode": "DOOR_STEP",
"category": "68c2a70190f1fdaabd8c0b8e",
"shipaOrEcommerce": false,
"insuredValue": 0,
"serviceType": "AIR_EXPORT",
"carrier": "AAJ",
"getAcknowledgementCopy": false,
"bookingDate": "2025-11-03T20:09:19.772Z",
"collectionEvents": [],
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:22.106Z",
"type": "IN",
"location": "United Kingdom",
"packageValueClaim": 20000,
"searchId": "59778268",
"__v": 0,
"extraCharges": {
"fuelSurcharge": {
"value": 0,
"type": "percentage",
"amount": 0
},
"onShippingFee": 6500,
"packagingFee": {
"value": 0,
"type": "price",
"amount": 0
}
},
"humanizedName": "BKG69090befabc57c5eb35b0f06",
"bookingStatus": "DUE",
"numberOfItems": 1,
"totalPackageDimensions": {
"length": 0,
"height": 0,
"width": 0,
"dimensionalWeight": 0,
"actualWeight": 0
},
"shippingFee": 6500,
"receiverZone": {
"id": 1,
"countries": ["England", "Wales", "United Kingdom"],
"default_supported_modes": ["D", "P"]
},
"id": "69090befabc57c5eb35b0f06"
},
"quote": {
"_id": "69090bf0abc57c5eb35b0f0d",
"booking": "69090befabc57c5eb35b0f06",
"shipTo": "Flat 3, 14 Oakwood Drive, Leeds, LS11 OAA, United Kingdom.",
"dateRaised": "2025-11-11T09:30:55.736Z",
"weight": 25,
"rate": "CR",
"subTotal": 6500,
"tax": 487.5,
"vat": 7.5,
"total": 6988,
"raisedBy": "68a47b9a2fc46e7e78da0ad8",
"name": "",
"senderCountry": "Nigeria, NG",
"receiverCountry": "United Kingdom, GB",
"senderHasNoNigerianAddress": false,
"tplService": "",
"hasCompleteBooking": true,
"carrier": "AAJ",
"addons": {
"totalAddonsPrice": 0,
"addons": []
},
"insurance": {
"type": "NE",
"fee": 0
},
"extraCharges": {
"fuelSurcharge": {
"value": 0,
"type": "percentage",
"amount": 0
},
"onShippingFee": 6500,
"packagingFee": {
"value": 0,
"type": "price",
"amount": 0
}
},
"items": [
{
"quantity": 1,
"price": 20000,
"hsCode": "62152000",
"name": "Bow tie",
"id": "68c2d050dbcf02dd65903ed1",
"excludePackingList": false,
"category": "Clothing & Fabrics",
"_id": "69090befabc57c5eb35b0f09",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z"
}
],
"packages": {
"packages": [
{
"actualWeight": 25,
"packageDimension": {
"length": 32,
"width": 25,
"height": 2,
"weight": 0.32,
"price": 0,
"_id": "69090befabc57c5eb35b0f08",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z",
"id": "69090befabc57c5eb35b0f08"
},
"predefinedDimension": "68fb3fa3bec965665202eacf",
"items": [
{
"quantity": 1,
"price": 20000,
"hsCode": "62152000",
"name": "Bow tie",
"id": "68c2d050dbcf02dd65903ed1",
"excludePackingList": false,
"category": "Clothing & Fabrics",
"_id": "69090befabc57c5eb35b0f09",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z"
}
],
"_id": "69090befabc57c5eb35b0f07",
"createdAt": "2025-11-03T20:09:19.776Z",
"updatedAt": "2025-11-03T20:09:19.776Z",
"multiple": 1,
"id": "69090befabc57c5eb35b0f07"
}
],
"itemsValue": 20000,
"packageType": "regular",
"type": "regular",
"addOns": [],
"items": []
},
"eta": {
"numberOfDays": 5,
"dateOfArrival": "2025-11-16T09:30:55.000000+01:00"
},
"fx": [
{
"rate": 1600,
"currency": "USD",
"amount": 4.367
},
{
"rate": 2070,
"currency": "GBP",
"amount": 3.376
},
{
"rate": 1750,
"currency": "EUR",
"amount": 3.993
}
],
"discounts": {
"discountsTotal": 0
},
"currency": "NGN",
"shippingFee": 6500,
"expirationDate": "2025-11-13T20:09:20.476Z",
"createdAt": "2025-11-03T20:09:20.477Z",
"updatedAt": "2025-11-11T09:30:55.965Z",
"__v": 0
},
"customerAcceptanceRequired": false
},
"status": 200,
"message": "Booking created successfully",
"timestamp": "2025-11-03T20:09:22.106Z"
}
Key response fields¶
| Field | Type | Description |
|---|---|---|
success |
boolean |
Indicates whether the booking was created successfully |
data.booking |
object |
The complete booking object with all details |
data.booking._id |
string |
Unique booking identifier (MongoDB ObjectId) |
data.booking.humanizedName |
string |
Human-readable booking reference (e.g., BKG69090befabc57c5eb35b0f06) |
data.booking.searchId |
string |
Short search-friendly ID for quick lookups |
data.booking.bookingStatus |
string |
Current status: DUE, PAID, COMPLETED, etc. |
data.booking.bookingState |
number |
State code. See Booking Enums |
data.booking.orderState |
number |
Order state code. See Booking Enums |
data.booking.subTotal |
number |
Subtotal before taxes (in NGN) |
data.booking.totalAmount |
number |
Total amount including VAT and fees |
data.booking.shippingFee |
number |
Base shipping fee |
data.booking.weight |
number |
Total weight of all packages |
data.booking.numberOfPackages |
number |
Count of packages in this booking |
data.booking.paid |
boolean |
Whether payment has been completed |
data.quote |
object |
Associated quote with pricing breakdown |
data.quote.tax |
number |
Tax amount (VAT) |
data.quote.vat |
number |
VAT percentage applied |
data.quote.total |
number |
Final quoted total |
data.quote.eta |
object |
Estimated delivery with numberOfDays and dateOfArrival |
data.quote.fx |
array |
Foreign exchange rates for USD, GBP, EUR |
data.customerAcceptanceRequired |
boolean |
Whether customer confirmation is needed before processing |
status |
number |
HTTP status code (200 for success) |
message |
string |
Success or error message |
timestamp |
string |
ISO timestamp of the response |
Error responses¶
Validation Error¶
{
"success": false,
"status": 400,
"message": "Validation failed",
"errors": [
{
"field": "receiver.contact.phone",
"message": "Invalid phone number format"
}
],
"timestamp": "2025-11-03T20:09:22.106Z"
}
Unauthorized¶
{
"success": false,
"status": 401,
"message": "Invalid or expired token",
"timestamp": "2025-11-03T20:09:22.106Z"
}
Tip: After creating a booking, use the returned
_idto update the booking, retrieve it by ID, or proceed to create a shipment.