> For the complete documentation index, see [llms.txt](https://docs.africanies.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.africanies.com/shipment.md).

# Shipment

## Get shipment rates.

> 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.

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Shipment","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"default":[]}],"components":{"securitySchemes":{"default":{"type":"apiKey","name":"Authorization","in":"header","description":"Use your base64-encoded public_key:private_key value."}},"schemas":{"ShipmentRateReadRequest":{"type":"object","properties":{"addresses":{"type":"object","description":"Address information for sender and receiver.","properties":{"sender":{"type":"object","description":"Sender address details.","properties":{"first_name":{"type":"string","description":"Sender's first name."},"last_name":{"type":"string","description":"Sender's last name."},"email":{"type":"string","description":"Sender's email address."},"phone":{"type":"string","description":"Sender's phone number."},"alternate_phone":{"type":"string","description":"nullable Sender's alternate phone.","nullable":true},"country":{"type":"string","description":"Sender's country code."},"state":{"type":"string","description":"Sender's state code."},"city":{"type":"string","description":"Sender's city."},"address":{"type":"string","description":"Sender's address."},"address_in_detail":{"type":"string","description":"Detailed sender address."},"address_landmark":{"type":"string","description":"Sender address landmark."},"zip_code":{"type":"string","description":"Sender's zip code."},"type":{"type":"string","description":"Address type."},"longitude":{"type":"number","description":"Sender's longitude."},"latitude":{"type":"number","description":"Sender's latitude."},"street_number":{"type":"string","description":"nullable Street number.","nullable":true},"street_name":{"type":"string","description":"nullable Street name.","nullable":true},"google_address":{"type":"string","description":"Google address."}},"required":["first_name","last_name","email","phone","country","state","city","address","address_in_detail","address_landmark","zip_code","type","longitude","latitude","google_address"]},"receiver":{"type":"object","description":"Receiver address details.","properties":{"first_name":{"type":"string","description":"Receiver's first name."},"last_name":{"type":"string","description":"Receiver's last name."},"email":{"type":"string","description":"Receiver's email address."},"phone":{"type":"string","description":"Receiver's phone number."},"alternate_phone":{"type":"string","description":"nullable Receiver's alternate phone.","nullable":true},"country":{"type":"string","description":"Receiver's country code."},"state":{"type":"string","description":"Receiver's state code."},"city":{"type":"string","description":"Receiver's city."},"address":{"type":"string","description":"Receiver's address."},"address_in_detail":{"type":"string","description":"Detailed receiver address."},"address_landmark":{"type":"string","description":"Receiver address landmark."},"zip_code":{"type":"string","description":"Receiver's zip code."},"type":{"type":"string","description":"Address type."},"longitude":{"type":"number","description":"Receiver's longitude."},"latitude":{"type":"number","description":"Receiver's latitude."},"street_number":{"type":"string","description":"nullable Street number.","nullable":true},"street_name":{"type":"string","description":"nullable Street name.","nullable":true},"google_address":{"type":"string","description":"Google address."}},"required":["first_name","last_name","email","phone","country","state","city","address","address_in_detail","address_landmark","zip_code","type","longitude","latitude","google_address"]}},"required":["sender","receiver"]},"boxes":{"type":"array","description":"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.","items":{"type":"string"}},"units":{"type":"object","description":"Measurement units for box dimensions and mass. This must match the selected shipment mode.","properties":{"mass":{"type":"string","description":"Mass unit. Use `KG` for SFN and `lbs` for STN to get accurate rates."},"dimension":{"type":"string","description":"Dimension unit. Use `cm` for SFN and `INCHES` for STN to get accurate rates."}},"required":["mass","dimension"]},"last_mile_delivery":{"type":"boolean","description":"optional Set to true for doorstep delivery to the receiver's address. Set to false if the customer will pick up from warehouse."},"is_insured":{"type":"string","description":"optional Set to `1` to price insurance in the quote, or `0` for no insurance."}},"required":["addresses","boxes","units"]}}},"paths":{"/api/v1/shipment/rates":{"post":{"summary":"Get shipment rates.","operationId":"getShipmentRates","description":"This endpoint retrieves shipping rates.\nbased on the provided shipment details including sender/receiver\ninformation, package dimensions, and items.\n\n**Measurement & Delivery Notes**\n- `last_mile_delivery` means doorstep delivery to the final receiver address.\n  If false, the shipment is for warehouse pickup instead.\n- `units` controls how box dimensions and weight are interpreted for pricing.\n- Unit rules by `X-Shipment-Mode`:\n  - `SFN` (shipping from Nigeria): use `cm` for dimensions and `KG` for mass.\n  - `STN` (shipping to Nigeria): use `INCHES` for dimensions and `lbs` for mass.\nUsing the wrong units for the selected mode can produce inaccurate costs.","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"charges":{"type":"object","properties":{"shipment_cost":{"type":"number"},"insurance_cost":{"type":"number"},"pickup_cost":{"type":"string"},"last_mile_delivery_cost":{"type":"integer"},"vat":{"type":"string","nullable":true}}},"total_amount":{"type":"number"},"discount_amount":{"type":"number"},"payment_amount":{"type":"number"},"total_item_value":{"type":"integer"},"others":{"type":"object","properties":{"min_day":{"type":"string"},"max_day":{"type":"string"},"currency":{"type":"string"}}},"mode":{"type":"string"}}}}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Shipment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentRateReadRequest"}}}}}}}}
```

## Purchase shipment.

> 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]\(/docs#file-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

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Shipment","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"default":[]}],"components":{"securitySchemes":{"default":{"type":"apiKey","name":"Authorization","in":"header","description":"Use your base64-encoded public_key:private_key value."}},"schemas":{"ShipmentPurchaseCreateRequest":{"type":"object","properties":{"address":{"type":"object","description":"Address information for sender and receiver.","properties":{"sender":{"type":"object","description":"Sender address details.","properties":{"first_name":{"type":"string","description":"Sender's first name."},"last_name":{"type":"string","description":"Sender's last name."},"email":{"type":"string","description":"Sender's email address."},"phone":{"type":"string","description":"Sender's phone number."},"alternate_phone":{"type":"string","description":"nullable Sender's alternate phone.","nullable":true},"country":{"type":"string","description":"Sender's country code."},"state":{"type":"string","description":"Sender's state code."},"city":{"type":"string","description":"Sender's city."},"address":{"type":"string","description":"Sender's address."},"address_in_detail":{"type":"string","description":"Detailed sender address."},"address_landmark":{"type":"string","description":"Sender address landmark.","nullable":true},"zip_code":{"type":"string","description":"Sender's zip code."},"type":{"type":"string","description":"Address type."},"longitude":{"type":"number","description":"Sender's longitude.","nullable":true},"latitude":{"type":"number","description":"Sender's latitude.","nullable":true},"street_number":{"type":"string","description":"nullable Street number.","nullable":true},"street_name":{"type":"string","description":"nullable Street name.","nullable":true},"google_address":{"type":"string","description":"Google address.","nullable":true}},"required":["first_name","last_name","email","phone","country","state","city","address","address_in_detail","address_landmark","zip_code","type","longitude","latitude","google_address"]},"receiver":{"type":"object","description":"Receiver address details.","properties":{"first_name":{"type":"string","description":"Receiver's first name."},"last_name":{"type":"string","description":"Receiver's last name."},"email":{"type":"string","description":"Receiver's email address."},"phone":{"type":"string","description":"Receiver's phone number."},"alternate_phone":{"type":"string","description":"nullable Receiver's alternate phone.","nullable":true},"country":{"type":"string","description":"Receiver's country code."},"state":{"type":"string","description":"Receiver's state code."},"city":{"type":"string","description":"Receiver's city."},"address":{"type":"string","description":"Receiver's address."},"address_in_detail":{"type":"string","description":"Detailed receiver address."},"address_landmark":{"type":"string","description":"Receiver address landmark.","nullable":true},"zip_code":{"type":"string","description":"Receiver's zip code."},"type":{"type":"string","description":"Address type."},"longitude":{"type":"number","description":"Receiver's longitude.","nullable":true},"latitude":{"type":"number","description":"Receiver's latitude.","nullable":true},"street_number":{"type":"string","description":"nullable Street number.","nullable":true},"street_name":{"type":"string","description":"nullable Street name.","nullable":true},"google_address":{"type":"string","description":"Google address.","nullable":true}},"required":["first_name","last_name","email","phone","country","state","city","address","address_in_detail","address_landmark","zip_code","type","longitude","latitude","google_address"]}},"required":["sender","receiver"]},"assigned_date":{"type":"string","description":"Booking/processing date for the shipment (format: Y-m-d). This should be a future date, usually current date + 1 day."},"boxes":{"type":"array","description":"Array of package boxes. Each box represents one package with its own dimensions, weight, and item list.","items":{"type":"string"}},"units":{"type":"object","description":"Measurement units for box dimensions and mass. This must match the selected shipment mode.","properties":{"mass":{"type":"string","description":"Mass unit. Use `KG` for SFN and `lbs` for STN to avoid pricing/booking mismatch."},"dimension":{"type":"string","description":"Dimension unit. Use `cm` for SFN and `INCHES` for STN to avoid pricing/booking mismatch."}},"required":["mass","dimension"]},"type":{"type":"string","description":"optional Shipment type."},"product_code":{"type":"string","description":"optional Product code: `P` for parcel or `D` for document shipment."},"is_insured":{"type":"string","description":"optional Set to `1` to add shipment insurance (additional cost applies), or `0` for no insurance."},"file_is_url":{"type":"string","description":"optional Purchase shipment only. Flag forwarded to the backend indicating the format to use for `waybill_doc`: `0` for file reference, `1` for URL."},"external_reference":{"type":"string","description":"Unique external reference for this shipment. This is useful for reconciliation and matching records across systems."},"shipment_method_slug":{"type":"string","description":"Carrier method slug selected by the user. This determines the shipment carrier, pricing, and estimated delivery timeline."}},"required":["address","assigned_date","boxes","units","external_reference","shipment_method_slug"]}}},"paths":{"/api/v1/shipment/purchase":{"post":{"summary":"Purchase shipment.","operationId":"purchaseShipment","description":"This endpoint purchases a shipment based on the provided shipment details\nincluding sender/receiver information, package dimensions, and items.\n\n**Important Info**\n- If you are shipping to any European country, you must provide invoice document(s) for the item(s) being shipped.\n- Invoice and photo files can be submitted as S3 keys (after signed URL upload) or as full URLs using root-level `file_is_url`.\n- Signed URL guide: [Generate signed URL for file uploads](/docs#file-generate-signed-url-for-file-uploads)\n- `units` must match shipment mode for accurate pricing and successful booking:\n  - `SFN` (shipping from Nigeria): `cm` and `KG`\n  - `STN` (shipping to Nigeria): `INCHES` and `lbs`\n- If you selected `last_mile_delivery` during rate request, the shipment will be booked for doorstep delivery.\n\n**File Upload Workflow:**\n1. First, call `/api/v1/file/generate` to get signed URLs for your files\n2. Upload your files directly to S3 using the returned `upload_url` values\n3. Use the returned `s3_key` values in `documents_s3_key` or `photos_s3_key` arrays","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"reference":{"type":"string"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"documents":{"type":"object","properties":{"waybill_doc":{"type":"string"},"insurance_doc":{"type":"string"},"invoice_doc":{"type":"string"}}},"waybill_is_url":{"type":"integer"},"insurance_is_url":{"type":"integer"},"invoice_is_url":{"type":"integer"},"mode":{"type":"string"}}}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Shipment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentPurchaseCreateRequest"}}}}}}}}
```

## Track shipment.

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

```json
{"openapi":"3.0.3","info":{"title":"AfricanIES - Sandbox API Documentation","version":"1.0.0"},"tags":[{"name":"Shipment","description":""}],"servers":[{"url":"https://api-sandbox.africaniestest.com"}],"security":[{"default":[]}],"components":{"securitySchemes":{"default":{"type":"apiKey","name":"Authorization","in":"header","description":"Use your base64-encoded public_key:private_key value."}}},"paths":{"/api/v1/shipment/track/{tracking_number}":{"post":{"summary":"Track shipment.","operationId":"trackShipment","description":"This endpoint tracks a shipment using the shipment ID and tracking number.","parameters":[{"in":"header","name":"X-Shipment-Mode","description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"shipment_id":{"type":"string"},"tracking_number":{"type":"string"},"status":{"type":"string"},"location":{"type":"string"},"estimated_delivery":{"type":"string"}}}}}}}},"500":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array"}}}}}}},"tags":["Shipment"]}}}}
```