Create Booking¶

Bookings Step 1: Create Order

Create a new shipment booking with sender/receiver details, package information, and delivery preferences. This is the first step in the shipping workflow.

Returns

Booking object with quote

Auth

Bearer token required

Next Step

Process Booking

Endpoint¶

POST Authenticated

URL: {{base_url}}/partner/booking/create-booking/

Prerequisites

Get your API Key from the Partner Portal
Retrieve available categories using Get Categories endpoint

Required Headers¶

Header	Value
`Authorization`	`Bearer {{ token }}`
`Content-Type`	`application/json`

cURL Example¶

curl -X POST "https://booking.aajexpress.org/api/v2/partner/booking/create-booking/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {
      "contact": { "name": "John Doe", "phone": "+2349012345678", "email": "john@example.com" },
      "addressDetails": { "addressLine1": "123 Main St", "city": "Lagos", "state": "Lagos", "country": "Nigeria", "countryCode": "NG", "stateOrProvinceCode": "LA", "postalCode": "100001" }
    },
    "receiver": {
      "contact": { "name": "Jane Doe", "phone": "+2348012345678", "email": "jane@example.com" },
      "addressDetails": { "addressLine1": "456 Airport Rd", "city": "Warri", "state": "Delta", "country": "Nigeria", "countryCode": "NG", "stateOrProvinceCode": "DE", "postalCode": "332213" }
    },
    "packages": {
      "packages": [{ "actualWeight": 5, "items": [{ "name": "Documents", "quantity": 1 }] }]
    },
    "serviceType": "DOMESTIC",
    "deliveryMode": "DOOR_STEP",
    "category": "YOUR_CATEGORY_ID"
  }'

Request Body Structure¶

Top-Level Fields¶

Field	Type	Required	Description
`customBookingId`	`string`	No	Your own reference ID for this booking (max 100 chars)
`sender`	`object`	Yes	Sender contact and address details
`receiver`	`object`	Yes	Receiver contact and address details
`packages`	`object`	Yes	Package details including weight, dimensions, and items
`payments`	`object`	No	Payment configuration
`collectionMode`	`object`	No	How the package will be collected (pickup or drop-off)
`carrier`	`string`	No	Carrier code. Default: `AAJ`. Options: `AAJ`, `DHL`, `UPS`, `FDX`, `RDS`, `AMX`
`serviceType`	`string`	Yes	`DOMESTIC`, `AIR_EXPORT`, `SEA_EXPORT`, or `AIR_IMPORT`
`deliveryMode`	`string`	Yes	`DOOR_STEP` or `PICKUP`
`deliveryType`	`string`	No	`DROP_OFF` (default) or `SIGNATURE_REQUIRED`
`packageInsurance`	`string`	No	Insurance type. Default: `FR`. See options below
`category`	`string`	Yes*	Category ID from Get Categories. *Required for domestic orders
`description`	`string`	No	Shipment description (max 500 chars)
`getAcknowledgementCopy`	`boolean`	No	Request acknowledgement copy

sender Object (Click to expand)

The sender object contains contact information and address details.

sender.contact¶

Field	Type	Required	Validation
`owner`	`string`	No	Owner ID reference
`name`	`string`	Yes	2-50 characters, letters and spaces only
`phone`	`string`	Yes	E.164 format (e.g., `+2349037392830`), 10-16 chars
`email`	`string`	Yes	Valid email, 5-100 characters
`company`	`string`	No	Company name (max 100 chars)

sender.addressDetails¶

Field	Type	Required	Validation
`addressLine1`	`string`	Yes*	3-200 characters. *Required if `senderHasNoNigerianAddress` is false
`addressLine2`	`string`	No	3-200 characters
`apartmentNumber`	`string`	No	Max 20 characters
`city`	`string`	Yes	2-50 characters
`state`	`string`	Yes	2-50 characters
`country`	`string`	Yes	2-50 characters (e.g., `Nigeria`)
`countryCode`	`string`	Yes	Exactly 2 characters (e.g., `NG`)
`stateOrProvinceCode`	`string`	Yes	2-10 characters (e.g., `LA` for Lagos)
`postalCode`	`string`	Yes*	Postal/ZIP code. *Required if `senderHasNoNigerianAddress` is false
`landmark`	`string`	No	Max 100 characters
`location`	`string`	No	5-200 characters

receiver Object (Click to expand)

The receiver object contains contact information and address details.

receiver.contact¶

Field	Type	Required	Validation
`owner`	`string`	No	Owner ID reference
`name`	`string`	Yes	2-50 characters, letters and spaces only
`phone`	`string`	Yes	E.164 format (e.g., `+2348136737175`), 10-16 chars
`email`	`string`	Yes	Valid email, 5-100 characters
`company`	`string`	No	Company name (max 100 chars)

receiver.addressDetails¶

Field	Type	Required	Validation
`addressLine1`	`string`	Yes	3-200 characters
`addressLine2`	`string`	No	3-200 characters
`apartmentNumber`	`string`	No	Max 20 characters
`city`	`string`	Yes	2-50 characters
`state`	`string`	Yes	2-50 characters
`country`	`string`	Yes	2-50 characters (e.g., `Nigeria`)
`countryCode`	`string`	Yes	Exactly 2 characters (e.g., `NG`)
`stateOrProvinceCode`	`string`	Yes	2-10 characters (e.g., `DE` for Delta)
`areaOrProvince`	`string`	No	Area/province name
`postalCode`	`string`	Yes*	*Required for international orders
`landmark`	`string`	No	Max 100 characters
`location`	`string`	No	5-200 characters

International Orders

For international shipments, postalCode is required.

packages Object (Click to expand)

The packages object contains all package and item details.

packages (Top Level)¶

Field	Type	Required	Description
`packageType`	`string`	No	Default: `regular`
`itemsValue`	`number`	No	Total declared value of items (>= 0)
`packages`	`array`	Yes	Array of package objects (at least 1 required)
`addOns`	`array`	No	Additional services
`createMultiple`	`boolean`	No	Create multiple shipments

packages.packages[] (Each Package)¶

Field	Type	Required	Validation
`actualWeight`	`number`	Yes	Actual weight in KG (minimum 0.1)
`unitMeasurement`	`string`	No	Weight unit (e.g., `KGS`)
`predefinedDimension`	`string`	No	ID from Predefined Dimensions
`packageDimension`	`object`	No	Custom dimensions (if not using predefined)
`items`	`array`	No	Array of items in this package

packages.packages[].packageDimension¶

Field	Type	Required	Validation
`length`	`number`	Yes	Length in cm (>= 0)
`width`	`number`	Yes	Width in cm (>= 0)
`height`	`number`	Yes	Height in cm (>= 0)
`weight`	`number`	Yes	Dimensional weight (>= 0)
`price`	`number`	No	Price (>= 0)

packages.packages[].items[] (Each Item)¶

Field	Type	Required	Validation
`name`	`string`	Yes	Item name (1-100 characters)
`quantity`	`number`	Yes	Quantity (integer, minimum 1)
`price`	`number`	Yes*	Item price (>= 0). *Required for international orders
`unitMeasurement`	`string`	Yes*	Measurement unit (max 10 chars). *Required for international
`hsCode`	`string`	No	HS Code for customs (max 20 chars). Recommended for international
`manufacturerCountry`	`string`	Yes*	Country of manufacture (max 50 chars). *Required for international
`category`	`string`	No	Item category
`excludePackingList`	`boolean`	Yes*	Exclude from packing list. *Required for international

International Orders - Required Item Fields

For international shipments (AIR_EXPORT, SEA_EXPORT, AIR_IMPORT), the following item fields are required:

price - Declared value for customs
unitMeasurement - Weight/measurement unit
manufacturerCountry - Country of manufacture
excludePackingList - Whether to exclude from packing list
hsCode - Strongly recommended for customs clearance

payments Object (Click to expand)

Configure payment method for the booking.

Field	Type	Required	Description
`accountNumber`	`string`	No	Your account number
`transaction.generateTransaction`	`boolean`	No	Auto-generate transaction
`transaction.method`	`string`	No	`WALLET` or `CREDIT_FACILITY`

Payment Processing Note

You are NOT charged when you create a booking. Creating a booking generates a transaction record and invoice, but payment is only deducted when you call the Process Booking endpoint. This allows you to review the quote and booking details before committing to payment.

collectionMode Object (Click to expand)

Configure how the package will be collected from the sender.

Field	Type	Required	Description
`collectionType`	`string`	Yes	`PICKUP` or `DROPOFF`
`pickupDetails`	`object`	No	Required if collectionType is `PICKUP`
`pickupDetails.pickupDate`	`string`	Yes*	ISO date string. *Required for PICKUP
`pickupDetails.pickupTimeRange.from`	`string`	Yes*	Start time (e.g., `9:00 AM`)
`pickupDetails.pickupTimeRange.to`	`string`	Yes*	End time (e.g., `4:00 PM`)
`dropoffHub`	`string/object`	No	Hub ID for drop-off

Pickup Example

"collectionMode": {
  "collectionType": "PICKUP",
  "pickupDetails": {
    "pickupDate": "2025-12-15",
    "pickupTimeRange": {
      "from": "9:00 AM",
      "to": "4:00 PM"
    }
  }
}

Package Insurance Options¶

Code	Name	Description
`FR`	Free	No insurance coverage
`SD`	Standard	Standard coverage
`PM`	Premium	Premium coverage
`EI`	Electronic Insurance	For electronic items
`NE`	Non-Electronic Insurance	For non-electronic items
`HI`	Haulage Insurance	For haulage shipments

Sample Request¶

{
    "customBookingId": "FAV123456",
    "sender": {
        "contact": {
            "owner": "68ad8d134becd955242a3b6b",
            "name": "Max Double",
            "phone": "+2349037392830",
            "email": "sender@example.com"
        },
        "addressDetails": {
            "addressLine1": "Lagos",
            "addressLine2": "Lagos",
            "apartmentNumber": "2",
            "city": "lagos",
            "state": "Lagos",
            "country": "Nigeria",
            "stateOrProvinceCode": "LA",
            "countryCode": "NG",
            "postalCode": "20020015",
            "location": "Lagos, NGA"
        }
    },
    "receiver": {
        "contact": {
            "owner": "68a79ef6bcad064a830f051d",
            "name": "Anon User",
            "phone": "+2348136737175",
            "email": "receiver@example.com"
        },
        "addressDetails": {
            "addressLine1": "Airport Road",
            "addressLine2": "Effurun",
            "apartmentNumber": "41",
            "city": "warri",
            "state": "Delta",
            "country": "Nigeria",
            "stateOrProvinceCode": "DE",
            "areaOrProvince": "Airport road",
            "countryCode": "NG",
            "postalCode": "332213",
            "landmark": "Osubi Airport",
            "location": "HRV9XFM Okpe Delta"
        }
    },
    "packageInsurance": "EI",
    "packages": {
        "packageType": "regular",
        "itemsValue": 5000,
        "packages": [
            {
                "unitMeasurement": "KGS",
                "actualWeight": 5,
                "predefinedDimension": "68fb3fa3bec965665202ead3",
                "items": [
                    {
                        "name": "Phones",
                        "quantity": 5,
                        "unitMeasurement": "KGS",
                        "price": 1000
                    }
                ]
            }
        ],
        "addOns": [],
        "createMultiple": false
    },
    "payments": {
        "accountNumber": "558162",
        "transaction": {
            "generateTransaction": true,
            "method": "CREDIT_FACILITY"
        }
    },
    "carrier": "AAJ",
    "serviceType": "DOMESTIC",
    "deliveryMode": "DOOR_STEP",
    "description": "Shipment of packages",
    "category": "68526c5288d9322dd836f828",
    "getAcknowledgementCopy": false
}

Response¶

On successful creation, the API returns the booking object with the calculated quote.

Payment Not Deducted Yet

At this stage, a transaction and invoice are created but no payment is deducted. Payment is only processed when you call the Process Booking endpoint.

{
    "success": true,
    "data": {
        "booking": {
            "new": false,
            "origin": "regular",
            "sourcePlatform": "Transport-Pro-Corporate",
            "senderHasNoNigerianAddress": false,
            "receiver": {
                "contact": {
                    "owner": "68a79ef6bcad064a830f051d",
                    "name": "Anon User",
                    "phone": "+2348136737175",
                    "email": "receiver@example.com"
                },
                "addressDetails": {
                    "addressLine1": "Airport Road",
                    "addressLine2": "Effurun",
                    "apartmentNumber": "41",
                    "city": "warri",
                    "state": "Delta",
                    "country": "Nigeria",
                    "stateOrProvinceCode": "DE",
                    "countryCode": "NG",
                    "postalCode": "332213",
                    "landmark": "Osubi Airport",
                    "location": "HRV9XFM Okpe Delta",
                    "streetLines": []
                }
            },
            "sender": {
                "contact": {
                    "owner": "68ad8d134becd955242a3b6b",
                    "name": "Max Double",
                    "phone": "+2349037392830",
                    "email": "sender@example.com"
                },
                "addressDetails": {
                    "addressLine1": "Lagos",
                    "addressLine2": "Lagos",
                    "apartmentNumber": "2",
                    "city": "lagos",
                    "state": "Lagos",
                    "country": "Nigeria",
                    "countryCode": "NG",
                    "stateOrProvinceCode": "LA",
                    "postalCode": "20020015",
                    "location": "Lagos, NGA",
                    "streetLines": []
                }
            },
            "packageInsurance": "EI",
            "packages": {
                "packages": [
                    {
                        "actualWeight": 5,
                        "predefinedDimension": "68fb3fa3bec965665202ead3",
                        "items": [
                            {
                                "quantity": 5,
                                "price": 1000,
                                "unitMeasurement": "KGS",
                                "name": "Phones",
                                "excludePackingList": false,
                                "_id": "693abab0f2829e4b2e07696a"
                            }
                        ],
                        "_id": "693abab0f2829e4b2e076969",
                        "packageDimension": {
                            "length": 44,
                            "width": 22,
                            "height": 20.5,
                            "weight": 4,
                            "price": 4000
                        },
                        "multiple": 1
                    }
                ],
                "itemsValue": 5000,
                "createMultiple": false,
                "packageType": "regular",
                "type": "regular",
                "addOns": [],
                "items": []
            },
            "weight": 5,
            "addOns": [],
            "customerAcceptanceState": 0,
            "branchName": "Favs Inc",
            "servedBy": "Faith Philz",
            "shipmentRate": "SR",
            "orderState": 1,
            "bookingState": 1,
            "partner": false,
            "numberOfPackages": 1,
            "subTotal": 7226,
            "totalAmount": 7812,
            "promoCode": "SUMMER0245",
            "description": "Shipment of packages",
            "paid": false,
            "deliveryType": "DROP_OFF",
            "deliveryMode": "DOOR_STEP",
            "category": "68526c5288d9322dd836f828",
            "insuredValue": 0,
            "isDraft": false,
            "payments": {
                "accountNumber": "558162",
                "transaction": {
                    "method": "CREDIT_FACILITY",
                    "generateTransaction": true,
                    "allowAsynchronousTransaction": false
                }
            },
            "serviceType": "DOMESTIC",
            "carrier": "AAJ",
            "getAcknowledgementCopy": false,
            "_id": "693abab0f2829e4b2e076968",
            "bookingDate": "2025-12-11T12:36:00.809Z",
            "humanizedName": "BKG693abab0f2829e4b2e076968",
            "bookingStatus": "DUE",
            "numberOfItems": 5,
            "shippingFee": 7150.25,
            "id": "693abab0f2829e4b2e076968"
        },
        "quote": {
            "booking": "693abab0f2829e4b2e076968",
            "category": "68526c5288d9322dd836f828",
            "weight": 5,
            "rate": "SR",
            "subTotal": 7226,
            "tax": 585.375,
            "vat": 7.5,
            "total": 7812,
            "senderCountry": "Nigeria, NG",
            "receiverCountry": "Nigeria, NG",
            "carrier": "AAJ",
            "insurance": {
                "type": "EI",
                "fee": 75
            },
            "eta": {
                "numberOfDays": 5,
                "dateOfArrival": "2025-12-16T12:36:01.000000+01:00"
            },
            "fx": [
                { "rate": 1600, "currency": "USD", "amount": 4.883 },
                { "rate": 2070, "currency": "GBP", "amount": 3.774 },
                { "rate": 1750, "currency": "EUR", "amount": 4.464 }
            ],
            "currency": "NGN",
            "shippingFee": 7730,
            "_id": "693abab2f2829e4b2e076971",
            "expirationDate": "2025-12-21T12:36:02.031Z"
        }
    },
    "status": 201,
    "message": "Booking created successfully",
    "timestamp": "2025-12-11T12:36:03.805Z"
}

Key Response Fields¶

Field	Description
`booking._id`	Unique booking identifier. Use this for Process Booking
`booking.humanizedName`	Human-readable booking reference (e.g., `BKG693abab0...`)
`booking.bookingStatus`	Current status: `DUE` means awaiting processing
`booking.totalAmount`	Total amount to be paid (in NGN)
`booking.shippingFee`	Shipping cost before taxes
`booking.paid`	`false` - confirms payment not yet deducted
`quote.eta`	Estimated delivery time with `numberOfDays` and `dateOfArrival`
`quote.fx`	Foreign exchange rates for USD, GBP, EUR
`quote.insurance`	Insurance type and fee applied

Next Step¶

After creating a booking, proceed to Process Booking to generate the shipping label, get tracking ID, and complete payment.

Step 2: Process Booking

Generate shipping labels, get tracking ID, and complete payment

Process Booking