Creating a Delivery

Step 1 -- Get a delivery fee

curl --request POST \
  --url https://api.relay.chowdeck.com/relay/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.578997,
      "longitude": 3.349467
    },
    "estimated_order_amount": 500000
  }'

Request body:

Field	Type	Required	Description
`source_address`	object	Conditional	Coordinates of the pickup location. Required if `source_address_string` is not provided.
`source_address.latitude`	number	—	Latitude of the pickup point
`source_address.longitude`	number	—	Longitude of the pickup point
`source_address_string`	string	Conditional	Human-readable pickup address. Required if `source_address` is not provided.
`destination_address`	object	Conditional	Coordinates of the drop-off location. Required if `destination_address_string` is not provided.
`destination_address.latitude`	number	—	Latitude of the drop-off point
`destination_address.longitude`	number	—	Longitude of the drop-off point
`destination_address_string`	string	Conditional	Human-readable drop-off address. Required if `destination_address` is not provided.
`estimated_order_amount`	integer	No	Estimated value of the items being delivered, in the smallest currency unit. May affect pricing — pass `0` or omit if not applicable.

Provide either coordinates or an address string for each side of the delivery — not both required.

A successful response returns a fee object. Save the id -- you'll pass it as fee_id in the next step.

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

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.

Step 2 -- Create the delivery

curl --request POST \
  --url https://api.relay.chowdeck.com/relay/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"` if the source contact is initiating, `"receiving"` if the destination contact is
`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 address 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 address of the recipient
`destination_contact.country_code`	string	No	Country code (e.g. `"NG"`)
`reference`	string	No	Your own unique reference for this delivery. Auto-generated if not provided.
`estimated_order_amount`	integer	No	Estimated value of the items, in the smallest currency unit
`customer_delivery_note`	string	No	Instructions for the rider
`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

curl --request GET \
  --url https://api.relay.chowdeck.com/relay/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": "..."
}