Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Shipment

Get shipment rates.

post

This endpoint retrieves shipping rates. based on the provided shipment details including sender/receiver information, package dimensions, and items.

Measurement & Delivery Notes

  • last_mile_delivery means doorstep delivery to the final receiver address. If false, the shipment is for warehouse pickup instead.

  • units controls how box dimensions and weight are interpreted for pricing.

  • Unit rules by X-Shipment-Mode:

    • SFN (shipping from Nigeria): use cm for dimensions and KG for mass.

    • STN (shipping to Nigeria): use INCHES for dimensions and lbs for mass. Using the wrong units for the selected mode can produce inaccurate costs.

Authorizations
AuthorizationstringRequired

Use your base64-encoded public_key:private_key value.

Header parameters
X-Shipment-ModestringOptionalExample: SFN
Body
boxesstring[]Required

Array of package boxes. These boxes are basically containers for the items you want to ship. Let's say you want to ship a phone, and shoes, you have to put it in a box to package it. You can have multiple boxes in a shipment.

Example: [{"index":"0","length":"10","width":"10","height":"10","weight":"1.4","items":[{"name":"Smartphone","description":"Latest smartphone model","price":599.99,"product_hs_code":"0101210000","product_hs_code_description":"Telephones for cellular networks or for other wireless networks","weight":"1.4","unit_price":650,"country":"NG","quantity":"2","amount":"1300"}]}]
last_mile_deliverybooleanOptional

optional Set to true for doorstep delivery to the receiver's address. Set to false if the customer will pick up from warehouse.

Example: true
is_insuredstringOptional

optional Set to 1 to price insurance in the quote, or 0 for no insurance.

Example: 1
Responses
200Success
application/json
successbooleanOptionalExample: true
status_codeintegerOptionalExample: 200
messagestringOptionalExample: Shipment rates retrieved successfully
post/api/v1/shipment/rates
POST /api/v1/shipment/rates HTTP/1.1
Host: api-sandbox.africaniestest.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1449

{
  "addresses": {
    "sender": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "sender@example.com",
      "phone": "1234567890",
      "alternate_phone": null,
      "country": "NG",
      "state": "LA",
      "city": "Isolo",
      "address": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "address_in_detail": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "address_landmark": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "zip_code": "102214",
      "type": "sender",
      "longitude": 3.3792,
      "latitude": 6.5244,
      "street_number": null,
      "street_name": null,
      "google_address": "0"
    },
    "receiver": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "receiver@example.com",
      "phone": "0987654321",
      "alternate_phone": null,
      "country": "US",
      "state": "MA",
      "city": "Boston",
      "address": "17 Maryland St Boston MA USA",
      "address_in_detail": "17 Maryland St Boston MA USA",
      "address_landmark": "17 Maryland St Boston MA USA",
      "zip_code": "02125",
      "type": "receiver",
      "longitude": -71.0598,
      "latitude": 42.3601,
      "street_number": null,
      "street_name": null,
      "google_address": "0"
    }
  },
  "boxes": [
    {
      "index": "0",
      "length": "10",
      "width": "10",
      "height": "10",
      "weight": "1.4",
      "items": [
        {
          "name": "Smartphone",
          "description": "Latest smartphone model",
          "price": 599.99,
          "product_hs_code": "0101210000",
          "product_hs_code_description": "Telephones for cellular networks or for other wireless networks",
          "weight": "1.4",
          "unit_price": 650,
          "country": "NG",
          "quantity": "2",
          "amount": "1300"
        }
      ]
    }
  ],
  "units": {
    "dimension": "cm",
    "mass": "KG"
  },
  "last_mile_delivery": true,
  "is_insured": "1"
}
{
  "success": true,
  "status_code": 200,
  "message": "Shipment rates retrieved successfully",
  "data": [
    {
      "name": "AfricanIES Air Basic (STN)",
      "slug": "africanies_air_basic_stn",
      "charges": {
        "shipment_cost": 65.71,
        "insurance_cost": 3.59985,
        "pickup_cost": "5.72",
        "last_mile_delivery_cost": 0,
        "vat": null
      },
      "total_amount": 69.30985,
      "discount_amount": 5.999,
      "payment_amount": 63.31085,
      "total_item_value": 180,
      "others": {
        "min_day": "7",
        "max_day": "12",
        "currency": "USD"
      },
      "mode": "stn"
    },
    {
      "name": "AfricanIES Ocean Basic (STN)",
      "slug": "africanies_ocean_basic_stn",
      "charges": {
        "shipment_cost": 60.935827338129,
        "insurance_cost": 3.5282374100719,
        "pickup_cost": "5.72",
        "last_mile_delivery_cost": 0,
        "vat": null
      },
      "total_amount": 64.464064748201,
      "discount_amount": 5.5215827338129,
      "payment_amount": 58.942482014388,
      "total_item_value": 180,
      "others": {
        "min_day": "30",
        "max_day": "40",
        "currency": "USD"
      },
      "mode": "stn"
    },
    {
      "name": "AfricanIES Air Express (STN)",
      "slug": "africanies_air_express_stn",
      "charges": {
        "shipment_cost": 117.02,
        "insurance_cost": 4.4553,
        "pickup_cost": "5.72",
        "last_mile_delivery_cost": 0,
        "vat": null
      },
      "total_amount": 127.1953,
      "discount_amount": 2.93,
      "payment_amount": 124.2653,
      "total_item_value": 180,
      "others": {
        "min_day": "3",
        "max_day": "5",
        "currency": "USD"
      },
      "mode": "stn"
    }
  ]
}

Purchase shipment.

post

This endpoint purchases a shipment based on the provided shipment details including sender/receiver information, package dimensions, and items.

Important Info

  • If you are shipping to any European country, you must provide invoice document(s) for the item(s) being shipped.

  • Invoice and photo files can be submitted as S3 keys (after signed URL upload) or as full URLs using root-level file_is_url.

  • Signed URL guide: Generate signed URL for file uploads

  • units must match shipment mode for accurate pricing and successful booking:

    • SFN (shipping from Nigeria): cm and KG

    • STN (shipping to Nigeria): INCHES and lbs

  • If you selected last_mile_delivery during rate request, the shipment will be booked for doorstep delivery.

File Upload Workflow:

  1. First, call /api/v1/file/generate to get signed URLs for your files

  2. Upload your files directly to S3 using the returned upload_url values

  3. Use the returned s3_key values in documents_s3_key or photos_s3_key arrays

Authorizations
AuthorizationstringRequired

Use your base64-encoded public_key:private_key value.

Header parameters
X-Shipment-ModestringOptionalExample: SFN
Body
assigned_datestringRequired

Booking/processing date for the shipment (format: Y-m-d). This should be a future date, usually current date + 1 day.

Example: 2024-01-15
boxesstring[]Required

Array of package boxes. Each box represents one package with its own dimensions, weight, and item list.

Example: [{"length":10,"width":10,"height":10,"weight":5,"index":1,"items":[{"name":"Electronics Accessories","product_hs_code":"0101210000","product_hs_code_description":"Electronics accessories","description":"High-quality electronic accessories for mobile devices","weight":1.5,"unit_price":15,"quantity":2,"amount":30,"country":"US","documents_s3_key":["documents/invoice/b74cb57c-1b7d-4579-8c6b-bb550f38554f.pdf"],"photos_s3_key":["images/items/a85dc68d-2c8e-5680-9d7c-cc661f49665e.jpg"]}]}]
typestringOptional

optional Shipment type.

Example: shipment
product_codestringOptional

optional Product code: P for parcel or D for document shipment.

Example: P
is_insuredstringOptional

optional Set to 1 to add shipment insurance (additional cost applies), or 0 for no insurance.

Example: 0
file_is_urlstringOptional

optional Purchase shipment only. Flag forwarded to the backend indicating the format to use for waybill_doc: 0 for file reference, 1 for URL.

Example: 0
external_referencestringRequired

Unique external reference for this shipment. This is useful for reconciliation and matching records across systems.

Example: EXT-REF-12345
shipment_method_slugstringRequired

Carrier method slug selected by the user. This determines the shipment carrier, pricing, and estimated delivery timeline.

Example: africanies_air_express_sfn
Responses
200Success
application/json
successbooleanOptionalExample: true
status_codeintegerOptionalExample: 200
messagestringOptionalExample: Shipment purchased successfully
post/api/v1/shipment/purchase
POST /api/v1/shipment/purchase HTTP/1.1
Host: api-sandbox.africaniestest.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1718

{
  "address": {
    "sender": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "sender@example.com",
      "phone": "1234567890",
      "alternate_phone": null,
      "country": "NG",
      "state": "LA",
      "city": "Isolo",
      "address": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "address_in_detail": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "address_landmark": "19 Ademulegun St, Ilasamaja, Lagos 102214, Lagos, Nigeria",
      "zip_code": "102214",
      "type": "sender",
      "longitude": 3.3792,
      "latitude": 6.5244,
      "street_number": null,
      "street_name": null,
      "google_address": "0"
    },
    "receiver": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "receiver@example.com",
      "phone": "0987654321",
      "alternate_phone": null,
      "country": "US",
      "state": "MA",
      "city": "Boston",
      "address": "17 Maryland St Boston MA USA",
      "address_in_detail": "17 Maryland St Boston MA USA",
      "address_landmark": "17 Maryland St Boston MA USA",
      "zip_code": "02125",
      "type": "receiver",
      "longitude": -71.0598,
      "latitude": 42.3601,
      "street_number": null,
      "street_name": null,
      "google_address": "0"
    }
  },
  "assigned_date": "2024-01-15",
  "boxes": [
    {
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 5,
      "index": 1,
      "items": [
        {
          "name": "Electronics Accessories",
          "product_hs_code": "0101210000",
          "product_hs_code_description": "Electronics accessories",
          "description": "High-quality electronic accessories for mobile devices",
          "weight": 1.5,
          "unit_price": 15,
          "quantity": 2,
          "amount": 30,
          "country": "US",
          "documents_s3_key": [
            "documents/invoice/b74cb57c-1b7d-4579-8c6b-bb550f38554f.pdf"
          ],
          "photos_s3_key": [
            "images/items/a85dc68d-2c8e-5680-9d7c-cc661f49665e.jpg"
          ]
        }
      ]
    }
  ],
  "units": {
    "dimension": "cm",
    "mass": "KG"
  },
  "type": "shipment",
  "product_code": "P",
  "is_insured": "0",
  "file_is_url": "0",
  "external_reference": "EXT-REF-12345",
  "shipment_method_slug": "africanies_air_express_sfn"
}
{
  "success": true,
  "status_code": 200,
  "message": "Shipment purchased successfully",
  "data": {
    "reference": "EX-AIES-000001-142541",
    "tracking_number": "33Z7Z9379Z",
    "tracking_url": "https://sandbox.africaniestest.com/track-shipment?tracking_number=33Z7Z9379Z",
    "documents": {
      "waybill_doc": "https://aies-export.s3.amazonaws.com/documents/invoice/example-waybill.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=example",
      "insurance_doc": "https://aies-export.s3.amazonaws.com/documents/certificates/insurance/example-insurance.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=example",
      "invoice_doc": "https://aies-export.s3.amazonaws.com/documents/invoice/example-invoice.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=example"
    },
    "waybill_is_url": 1,
    "insurance_is_url": 1,
    "invoice_is_url": 1,
    "mode": "sfn"
  }
}

Track shipment.

post

This endpoint tracks a shipment using the shipment ID and tracking number.

Authorizations
AuthorizationstringRequired

Use your base64-encoded public_key:private_key value.

Path parameters
tracking_numberstringRequired

The tracking number.

Example: TRK789012
Header parameters
X-Shipment-ModestringOptionalExample: SFN
Responses
200Success
application/json
successbooleanOptionalExample: true
status_codeintegerOptionalExample: 200
messagestringOptionalExample: Shipment tracking retrieved successfully
post/api/v1/shipment/track/{tracking_number}
POST /api/v1/shipment/track/{tracking_number} HTTP/1.1
Host: api-sandbox.africaniestest.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "status_code": 200,
  "message": "Shipment tracking retrieved successfully",
  "data": {
    "shipment_id": "SH123456",
    "tracking_number": "TRK789012",
    "status": "in_transit",
    "location": "Lagos, Nigeria",
    "estimated_delivery": "2024-01-20"
  }
}
PreviousProduct HS Code
NextShipment Carriers

Last updated