Managing Deliveries

1. Get a delivery fee

Before creating a delivery, get a fee quote. Pass the source and destination coordinates and an optional estimated order value.

curl --request POST \
  --url https://api.chowdeck.com/merchant/{merchantReference}/delivery/fee \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "source_address": {
      "latitude": 6.601838,
      "longitude": 3.351486
    },
    "destination_address": {
      "latitude": 6.455027,
      "longitude": 3.384082
    },
    "estimated_order_amount": 500000
  }'

Request body:

Field	Type	Required	Description
`source_address`	object	Yes	Coordinates of the pickup location
`source_address.latitude`	number	Yes	Latitude of the pickup point
`source_address.longitude`	number	Yes	Longitude of the pickup point
`destination_address`	object	Yes	Coordinates of the drop-off location
`destination_address.latitude`	number	Yes	Latitude of the drop-off point
`destination_address.longitude`	number	Yes	Longitude of the drop-off point
`estimated_order_amount`	integer	No	Estimated value of the items being delivered, in the smallest currency unit. May affect pricing -- pass `0` if not applicable.

A successful response looks like this:

{
  "status": "success",
  "data": {
    "id": 12345,
    "total_amount": 80000,
    "delivery_amount": 70000,
    "service_amount": 50000,
    "safety_fee": 10000
  }
}

Save the id -- you'll pass it as fee_id in the next step.

All amounts are in the smallest currency unit. Divide by 100 for the display value (e.g. 80000 = ₦800).

Fee quotes are not permanent. Create your delivery promptly after getting a quote.

2. Create the delivery

Use the id from the fee response as fee_id to initiate the delivery.

curl --request POST \
  --url https://api.chowdeck.com/merchant/{merchantReference}/delivery \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fee_id": 12345,
    "reference": "my-delivery-ref-001",
    "item_type": "documents",
    "user_action": "sending",
    "source_contact": {
      "name": "Jane Smith",
      "phone": "08100000000"
    },
    "destination_contact": {
      "name": "John Doe",
      "phone": "08100000001"
    },
    "customer_delivery_note": "Please handle with care",
    "delivery_pin": 4821
  }'

Request body:

Field	Type	Required	Description
`fee_id`	integer	Yes	The `id` from the Get Delivery Fee response
`item_type`	string	Yes	Type of item being delivered (e.g. `"documents"`, `"electronics"`)
`user_action`	string	Yes	`"sending"` or `"receiving"`
`source_contact`	object	Yes	Details of the sender
`source_contact.name`	string	Yes	Full name of the sender
`source_contact.phone`	string	Yes	Phone number of the sender
`source_contact.email`	string	No	Email of the sender
`source_contact.country_code`	string	No	Country code (e.g. `"NG"`)
`destination_contact`	object	Yes	Details of the recipient
`destination_contact.name`	string	Yes	Full name of the recipient
`destination_contact.phone`	string	Yes	Phone number of the recipient
`destination_contact.email`	string	No	Email of the recipient
`destination_contact.country_code`	string	No	Country code (e.g. `"NG"`)
`reference`	string	No	Your own unique reference for this delivery
`estimated_order_amount`	integer	No	Estimated value of the items, in the smallest currency unit
`customer_delivery_note`	string	No	Instructions for the rider (e.g. `"Handle with care"`)
`customer_vendor_note`	string	No	Notes about the package contents
`delivery_pin`	integer	No	4-digit PIN (1000–9999) the recipient must present to the rider to confirm delivery
`notification_channels`	array	No	Channels to notify contacts: `"sms"`, `"email"`, `"whatsapp"`

A successful response returns the created delivery:

{
  "status": "success",
  "message": "Delivery created successfully",
  "data": {
    "id": 98765,
    "reference": "my-delivery-ref-001",
    "delivery_price": 80000,
    "delivery_pin": 4821,
    "tracking_url": "https://track.chowdeck.com/...",
    "status": "preparing"
  }
}

Track a delivery

Poll this endpoint to get the current status of a delivery.

curl --request GET \
  --url https://api.chowdeck.com/merchant/delivery/{reference} \
  --header 'Authorization: Bearer YOUR_API_KEY'

Delivery statuses:

Status	Description
`preparing`	Delivery created — rider assignment in progress
`awaiting_pickup`	Rider assigned and heading to pickup location
`in_transit`	Rider has collected the package
`success`	Package delivered successfully
`rejected`	Delivery was cancelled

Error responses

All failed requests return this shape:

{
  "status": "failed",
  "message": "..."
}