Skip to main content

​
Overview

This guide walks you through the complete flow of creating a delivery using the Chidori API. By the end, you will have:
  1. Obtained API keys from the dashboard
  2. Funded your wallet
  3. Calculated a delivery price
  4. Created a delivery
  5. Paid for the delivery

​
Prerequisites

Before you begin, make sure you have:
  • A Chidori account (sign up here)
  • A verified account (email verification required)
  • Basic knowledge of making HTTP requests

​
Step 1: Get your API keys

1

Access the Dashboard

Navigate to chidori.africa/dashboard and log in to your account.
2

Create an API Key

Go to the API Keys section and create a new key:
  • Name: Give it a descriptive name (e.g., “Production Key”)
  • Mode: Select Sandbox for testing or Live for production
  • Permissions: Select the permissions you need
Copy your API key immediately after creation. The full key is only shown once and cannot be retrieved later.
3

Store Your Key Securely

Your API key looks like this:
sk_live_7c9aa6f0-0f62-4bb2-a3aa-6c7bbf7b9a1a.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Store it securely in your environment variables.

​
Step 2: Fund your wallet

Before creating deliveries, you need funds in your wallet. Fund your wallet through the Chidori Dashboard:
  1. Go to the Wallet section in your dashboard
  2. Click Fund Wallet
  3. Choose your payment method and amount
  4. Complete the payment
For sandbox testing, you can fund your test wallet directly from the dashboard with any amount at no cost.

​
Step 3: Get a price estimate

Before creating a delivery, get a price estimate using the pickup and destination coordinates: 
curl -X POST https://api.chidori.africa/api/pricing/single \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup": {
      "lat": 6.5244,
      "lon": 3.3792
    },
    "destination": {
      "lat": 6.4654,
      "lon": 3.4064
    }
  }'

{
  "status": true,
  "data": {
    "distanceKm": 12.34,
    "durationSec": 900,
    "tempDeliveryId": "7c9aa6f0-0f62-4bb2-a3aa-6c7bbf7b9a1a",
    "pricing": {
      "distance_km": 12.34,
      "total_cost": 2500,
      "promo_applied": false,
      "promo_percent": 0
    }
  }
}
Save the tempDeliveryId from the response. You will need it to create the actual delivery.

​
Step 4: Create the delivery

Use the tempDeliveryId from the pricing response to create a delivery: 
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"
  }
}

​
Step 5: Pay for the delivery

Complete the delivery by paying for it from your wallet: 
curl -X POST https://api.chidori.africa/api/payments/charge \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryId": "abc123-def456-ghi789",
    "reference": "order_12345_payment"
  }'

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "amount": 2500,
    "paymentChannel": "Wallet",
    "reference": "order_12345_payment"
  }
}
Congratulations! You have successfully created and paid for your first delivery.

​
Next steps

Now that you have completed your first delivery, explore these features:

Bulk Deliveries

Create multiple deliveries from one pickup location.

Webhooks

Receive notifications when delivery status changes.

Real-time Tracking

Track driver locations via WebSocket (live only).

Environments

Learn about sandbox vs live environments.