Skip to main content

​
Overview

Retrieve a paginated list of all your deliveries with optional filtering by status, payment status, bulk, and date range.
Required permission: delivery:read

​
Endpoint

GET /api/deliveries/list

​
Request

​
Headers

​
X-API-Key
string
required
Your Chidori API key

​
Query parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"20"
Number of items per page (max 100)
​
status
string
Filter by delivery status (e.g., PENDING, IN_TRANSIT, DELIVERED)
​
bulk
string
Filter by bulk ID, or use true/false to filter bulk vs non-bulk deliveries
​
isPaid
string
Filter by payment status: true or false
​
createdFrom
string
Filter deliveries created from this timestamp (ISO 8601)
​
createdTo
string
Filter deliveries created up to this timestamp (ISO 8601)

​
Response

​
Success response

​
status
boolean
Always true for successful requests
​
data
object

​
Examples

​
Basic listing

curl "https://api.chidori.africa/api/deliveries/list?page=1&limit=20" \
  -H "X-API-Key: sk_live_xxx.yyy"

​
With filters

# Get unpaid deliveries
curl "https://api.chidori.africa/api/deliveries/list?isPaid=false" \
  -H "X-API-Key: sk_live_xxx.yyy"

# Get deliveries in transit
curl "https://api.chidori.africa/api/deliveries/list?status=IN_TRANSIT" \
  -H "X-API-Key: sk_live_xxx.yyy"

# Get bulk deliveries only
curl "https://api.chidori.africa/api/deliveries/list?bulk=true" \
  -H "X-API-Key: sk_live_xxx.yyy"

# Get deliveries from a specific bulk
curl "https://api.chidori.africa/api/deliveries/list?bulk=1a4f1a5e-5b79-4c4a-a0d4-4c5c7b7bb1aa" \
  -H "X-API-Key: sk_live_xxx.yyy"

# Get deliveries from date range
curl "https://api.chidori.africa/api/deliveries/list?createdFrom=2025-01-01T00:00:00Z&createdTo=2025-01-31T23:59:59Z" \
  -H "X-API-Key: sk_live_xxx.yyy"

{
  "status": true,
  "data": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "items": [
      {
        "id": "abc123-def456-ghi789",
        "trackingId": "CHI-ABC123",
        "deliveryStatus": "DELIVERED",
        "deliveryName": "Office Supplies",
        "deliveryAmount": 2500,
        "isPaid": true,
        "bulk": null,
        "createdAt": "2025-01-15T10:00:00.000Z"
      },
      {
        "id": "def456-ghi789-jkl012",
        "trackingId": "CHI-DEF456",
        "deliveryStatus": "IN_TRANSIT",
        "deliveryName": "Electronics",
        "deliveryAmount": 3500,
        "isPaid": true,
        "bulk": "1a4f1a5e-5b79-4c4a-a0d4-4c5c7b7bb1aa",
        "createdAt": "2025-01-15T11:00:00.000Z"
      }
    ]
  }
}

​
Pagination

To iterate through all deliveries: 
async function getAllDeliveries() {
  const allDeliveries = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api.chidori.africa/api/deliveries/list?page=${page}&limit=100`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const { data } = await response.json();
    
    allDeliveries.push(...data.items);
    hasMore = data.items.length === 100;
    page++;
  }
  
  return allDeliveries;
}

​
Filter combinations

You can combine multiple filters: 
# Unpaid pending deliveries from January
curl "https://api.chidori.africa/api/deliveries/list?status=PENDING&isPaid=false&createdFrom=2025-01-01T00:00:00Z&createdTo=2025-01-31T23:59:59Z" \
  -H "X-API-Key: sk_live_xxx.yyy"

​
Next steps

Get Delivery

Get detailed information about a specific delivery

Webhooks

Get notified when delivery status changes