Skip to main content

Overview

Create a delivery using a tempDeliveryId obtained from the pricing endpoint. This converts the price estimate into an actual delivery that can be paid for and dispatched.
Required permission: delivery:create

Endpoint

POST /api/deliveries/create

Request

Headers

X-API-Key
string
required
Your Chidori API key
Content-Type
string
required
Must be application/json

Body parameters

tempDeliveryId
string
required
The temporary delivery ID from the pricing response
deliveryName
string
A descriptive name for the delivery (e.g., “Office Supplies”)
deliveryType
string
Type of delivery. Options: SendDelivery or RequestPickup
receiverPhoneNumber
string
Phone number of the recipient (e.g., +2348012345678)
senderPhoneNumber
string
Phone number of the sender (e.g., +2348087654321)
additionalNotes
string
Any special instructions for the driver
scheduledTime
string
ISO 8601 datetime for scheduled deliveries (e.g., 2025-01-15T10:00:00.000Z)

Response

Success response

status
boolean
Always true for successful requests
data
object

Examples

curl -X POST https://api.chidori.africa/api/deliveries/create \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "tempDeliveryId": "7c9aa6f0-0f62-4bb2-a3aa-6c7bbf7b9a1a",
    "deliveryName": "Office Supplies",
    "receiverPhoneNumber": "+2348012345678",
    "senderPhoneNumber": "+2348087654321",
    "additionalNotes": "Please call before delivery"
  }'
{
  "status": true,
  "data": {
    "id": "abc123-def456-ghi789",
    "trackingId": "CHI-ABC123",
    "deliveryStatus": "PENDING",
    "bulk": null,
    "order": null
  }
}

Delivery workflow

1

Get price estimate

Call /api/pricing/single to get a tempDeliveryId
2

Create delivery

Use this endpoint with the tempDeliveryId
3

Pay for delivery

Call /api/payments/charge with the delivery ID
4

Track delivery

Use webhooks or WebSocket for real-time updates

Delivery statuses

StatusDescription
PENDINGDelivery created, awaiting payment
PAIDPayment received, awaiting driver assignment
ASSIGNEDDriver assigned to the delivery
PICKED_UPDriver has picked up the package
IN_TRANSITPackage is on the way to destination
DELIVEREDPackage successfully delivered
CANCELLEDDelivery was cancelled
The tempDeliveryId expires after a certain period. If you receive a “not found” error, request a new price estimate.

Next steps