Create Quote¶

Quotes Write

Price a shipment request and receive AAJ-generated rates plus eligible partner courier quotes. Returns comprehensive pricing with taxes, surcharges, FX conversions, and ETAs.

Returns

Multiple rate options

Auth

Bearer token required

Use cases

Rate shopping · Price comparison · Sales tools

Endpoint overview¶

POST Authenticated

URL: {{base_url}}/quote

Returns AAJ rates plus third-party carrier options when available.
Includes real-time FX conversions for USD, GBP, EUR.
Calculates ETA based on origin, destination, and service type.

Required headers¶

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

Request body structure¶

Field	Type	Required	Description
`sender.addressDetails.country`	`string`	Yes	Full country name for origin
`sender.addressDetails.countryCode`	`string`	Yes	ISO 3166-1 alpha-2 code (e.g., `NG`)
`sender.addressDetails.stateOrProvinceCode`	`string`	Yes	State/province code
`sender.addressDetails.state`	`string`	Yes	State/province name
`sender.addressDetails.postalCode`	`string`	Yes	Postal/ZIP code
`sender.addressDetails.city`	`string`	Yes	City name
`receiver.addressDetails.country`	`string`	Yes	Full country name for destination
`receiver.addressDetails.countryCode`	`string`	Yes	ISO 3166-1 alpha-2 code (e.g., `US`)
`receiver.addressDetails.stateOrProvinceCode`	`string`	Yes	State/province code
`receiver.addressDetails.state`	`string`	Yes	State/province name
`receiver.addressDetails.postalCode`	`string`	Yes	Postal/ZIP code
`receiver.addressDetails.city`	`string`	Yes	City name
`serviceType`	`string`	Yes	Service tier (e.g., `AIR_EXPORT`)
`carrier`	`string`	Yes	Primary carrier code (e.g., `AAJ`)
`tplService`	`string`	No	Specific third-party logistics service
`packages.itemsValue`	`number`	Yes	Total declared value of items
`packages.packageType`	`string`	Yes	Package profile (`regular`, `document`, etc.)
`packages.packages[]`	`array`	Yes	Array of package definitions
`packages.packages[].actualWeight`	`number`	Yes	Actual weight in kg
`packages.packages[].predefinedDimension`	`string`	No	Reference ID to saved dimension profile
`packages.packages[].items[]`	`array`	No	Line items for customs and insurance
`deliveryMode`	`string`	Yes	`DOOR_STEP` or `PICKUP`
`optionalTplRates[]`	`array`	No	Third-party providers to include (e.g., `["FDX", "DHL", "UPS"]`)

Sample request¶

{
  "sender": {
    "addressDetails": {
      "country": "Nigeria",
      "countryCode": "NG",
      "stateOrProvinceCode": "lagos",
      "state": "lagos",
      "postalCode": "100123",
      "city": "lagos"
    }
  },
  "receiver": {
    "addressDetails": {
      "country": "United States",
      "countryCode": "US",
      "stateOrProvinceCode": "AL",
      "postalCode": "29620",
      "state": "Alabama",
      "city": "Abbeville"
    }
  },
  "serviceType": "AIR_EXPORT",
  "carrier": "AAJ",
  "packages": {
    "itemsValue": 100000,
    "packageType": "regular",
    "packages": [
      {
        "actualWeight": 7.5,
        "predefinedDimension": "68fb3fa3bec965665202ead1",
        "items": [
          {
            "id": "68c2d050dbcf02dd65903cda",
            "quantity": 100,
            "price": 1000
          }
        ]
      }
    ]
  },
  "deliveryMode": "DOOR_STEP"
}

Response¶

{
  "success": true,
  "message": "quote created",
  "data": {
    "quotes": [
      {
        "subTotal": 32010,
        "addons": {
          "total_addons_price": 0,
          "addons": []
        },
        "extraCharges": {
          "fuel_surcharge": {
            "value": 0,
            "type": "percentage",
            "amount": 0
          },
          "on_shipping_fee": 32010,
          "packaging_fee": {
            "value": 0,
            "type": "price",
            "amount": 0
          },
          "home_delivery_fee": 0
        },
        "shippingFee": 32010,
        "total": 34411,
        "tax": 2400.75,
        "discounts": {
          "discounts_total": 0
        },
        "booking": "688c943e639d2d6c59b1bdaa",
        "shipTo": "73 HOLBURN STREET",
        "weight": 2,
        "rate": "SR",
        "insurance": {
          "type": "FR",
          "fee": 0
        },
        "vat": 7.5,
        "packages": {
          "packages": [
            {
              "actualWeight": 2,
              "packageDimension": {
                "length": 1,
                "width": 1,
                "height": 1,
                "weight": 0,
                "price": 0,
                "id": "688c943e639d2d6c59b1bdac"
              },
              "unitMeasurement": "KGS",
              "id": "688c943e639d2d6c59b1bdab"
            }
          ],
          "itemsValue": 3500,
          "packageType": "regular",
          "addOns": [],
          "items": []
        },
        "senderCountry": "Nigeria, NG",
        "receiverCountry": "United Kingdom, GB",
        "carrier": "AAJ",
        "tplService": "",
        "eta": {
          "number_of_days": 5,
          "date_of_arrival": "2025-08-06T10:17:34.000000+01:00"
        },
        "fx": [
          {
            "rate": 1600,
            "currency": "USD",
            "amount": 21.507
          },
          {
            "rate": 2070,
            "currency": "GBP",
            "amount": 16.624
          },
          {
            "rate": 1750,
            "currency": "EUR",
            "amount": 19.663
          }
        ],
        "dateRaised": "2025-08-01T10:17:34.500Z",
        "currency": "NGN",
        "hasCompleteBooking": false
      }
    ],
    "courier_rates": [
      {
        "network": {
          "networkCode": "1^11",
          "networkDescription": "DPD TWO DAY"
        },
        "isLiabilityAllowed": false,
        "invoiceRequired": false,
        "product": {
          "productCode": "1^1",
          "productDescription": "Parcel"
        },
        "service": {
          "serviceCode": "1^1",
          "serviceDescription": "Dpd Two Day"
        },
        "amount": 34411,
        "currency": "NGN",
        "image": "",
        "provider": "DPD UK",
        "servicelevel": {
          "token": "DPD TWO DAY",
          "name": "DPD UK",
          "description": "DPD TWO DAY"
        },
        "object_id": "1^11"
      },
      {
        "network": {
          "networkCode": "1^12",
          "networkDescription": "DPD NEXT DAY"
        },
        "isLiabilityAllowed": false,
        "invoiceRequired": false,
        "product": {
          "productCode": "1^1",
          "productDescription": "Parcel"
        },
        "service": {
          "serviceCode": "1^2",
          "serviceDescription": "Dpd Next Day"
        },
        "amount": 34411,
        "currency": "NGN",
        "image": "",
        "provider": "DPD UK",
        "servicelevel": {
          "token": "DPD NEXT DAY",
          "name": "DPD UK",
          "description": "DPD NEXT DAY"
        },
        "object_id": "1^12"
      }
    ]
  }
}

Key response fields¶

Field	Type	Description
`success`	`boolean`	Whether the quote request was successful
`data.quotes[]`	`array`	AAJ-issued quote options with pricing, taxes, FX, and ETAs
`data.quotes[].total`	`number`	Total amount payable including surcharges and tax
`data.quotes[].subTotal`	`number`	Base price before taxes and fees
`data.quotes[].tax`	`number`	Tax amount (VAT)
`data.quotes[].vat`	`number`	VAT percentage applied
`data.quotes[].shippingFee`	`number`	Base shipping fee
`data.quotes[].extraCharges`	`object`	Breakdown of surcharges (fuel, packaging, delivery)
`data.quotes[].eta`	`object`	Estimated delivery: `number_of_days` and `date_of_arrival`
`data.quotes[].fx[]`	`array`	Foreign exchange conversions (USD, GBP, EUR)
`data.quotes[].booking`	`string`	Reference booking ID for converting to confirmed shipment
`data.quotes[].insurance`	`object`	Insurance type and fee
`data.courier_rates[]`	`array`	Alternative partner courier rates when available
`data.courier_rates[].amount`	`number`	Partner courier price
`data.courier_rates[].provider`	`string`	Carrier providing the quoted service

Error responses¶

Invalid Address¶

{
  "success": false,
  "status": 400,
  "message": "Invalid destination address",
  "errors": [
    {
      "field": "receiver.addressDetails.postalCode",
      "message": "Postal code not found for specified city/state"
    }
  ]
}

Tip: If predefinedDimension is not available, include an explicit packageDimension block with length, width, height, and unitMeasurement for each package. See Predefined Dimensions for standard sizes.