Kilo Docs

Docs / Deliveries/ Create a delivery

Create a delivery

Updated Aug 9, 2026

POST /api/v1/deliveries
Content-Type: application/json
Authorization: Bearer sk_live_...

Before you call

  1. Call Capabilities & locations so you know which services, warehouses, payments, and service locations this org actually offers.
  2. Delivery services must be enabled in dashboard settings (API create rejects disabled serviceKind).
  3. Add allowed image hosts under API & Webhooks.
  4. Package photos must be https:// URLs on those hosts. Kilo downloads them and stores them. Private IPs are blocked.

Minimal pickup_delivery example

{
  "serviceKind": "pickup_delivery",
  "deliveryMode": "pickup",
  "senderName": "Ada Lovelace",
  "senderPhone": "+2348012345678",
  "senderEmail": "ada@example.com",
  "pickupContactSameAsSender": true,
  "receiverName": "Grace Hopper",
  "receiverPhone": "+2348098765432",
  "pickupAddress": "12 Admiralty Way, Lekki",
  "pickupCoords": { "lng": 3.4721, "lat": 6.4474 },
  "deliveryAddress": "Victoria Island Office",
  "deliveryCoords": { "lng": 3.4219, "lat": 6.4281 },
  "packageDescription": "Documents envelope",
  "packageSize": "small",
  "packageImages": [
    "https://cdn.yourbot.com/jobs/abc/package-1.jpg"
  ],
  "customerCollectionMethod": "cash_on_delivery"
}

Important fields (plain English)

Field Meaning
serviceKind pickup_delivery or errand
deliveryMode pickup (rider goes to an address) or warehouse (needs warehouseId)
pickupCoords / deliveryCoords Map coordinates — not optional for real routing
packageImages 1–6 HTTPS image URLs from allowlisted hosts
customerCollectionMethod cash_on_delivery or online_checkout (must be allowed in your settings)
isPODEnabled + podAmount Cash to collect from the receiver (only if enabled for your fleet)

What you get back

{
  "ok": true,
  "delivery": {
    "id": "uuid",
    "status": "pending",
    "access_code": "ABC123",
    "request_source": "api"
  }
}

Save id. Use it for get / cancel / webhook matching.

Common errors

code / message Fix
Image host not allowlisted Add the CDN hostname in Settings → API & Webhooks
Service kind disabled Enable the service in Delivery settings
Coverage / location blocked Job is outside your configured coverage
Validation failed Read fieldErrors — a required field is missing

Next

← AuthenticationGet, list, cancel →