Quickstart

Four calls from nothing to a booked parcel. Use a test key and none of it is real.

Create a test key first — it starts with sw_test_, works immediately, and needs no approval. Every example below runs against it.

1. Find the destination town

Customers collect from a town, so start by finding its id.

GET/v1/towns?search=kisumu

bash

curl https://api.shopinn.co.ke/api/sendway/v1/towns?search=kisumu \
  -H "Authorization: Bearer sw_test_YOUR_KEY"

json

{
  "object": "list",
  "data": [
    {
      "object": "town",
      "id": "c3e0e7c5-7925-4c8f-8f01-f273acb9b29d",
      "name": "Ahero",
      "sub_county": "Nyando",
      "county": "Kisumu",
      "zone": 3,
      "latitude": -0.1667,
      "longitude": 34.9167
    }
  ],
  "counties": ["Baringo", "Bomet", "..."]
}

2. Price it

Quote before your customer pays, so the delivery fee you charge is the one you will be charged.

POST/v1/quotes

bash

curl https://api.shopinn.co.ke/api/sendway/v1/quotes \
  -H "Authorization: Bearer sw_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package_size": "S",
    "weight_kg": 2,
    "delivery_mode": "STATION",
    "origin_lat": -1.2864,
    "origin_lng": 36.8172,
    "dest_town_id": "c3e0e7c5-7925-4c8f-8f01-f273acb9b29d"
  }'

json

{
  "object": "quote",
  "currency": "KES",
  "delivery_fee": 350,
  "insurance": 0,
  "total": 350,
  "distance_km": 245.3,
  "package_size": "S",
  "distance_band": "FAR",
  "requires_pickup_station": false,
  "breakdown": ["S package · Zone 3 pickup town"]
}

3. Book it

When the order is paid on your side, create the parcel. Nothing is charged here — it joins the batch a rider will collect.

POST/v1/parcels

bash

curl https://api.shopinn.co.ke/api/sendway/v1/parcels \
  -H "Authorization: Bearer sw_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-1042" \
  -d '{
    "recipient_name": "Achieng Otieno",
    "recipient_phone": "0712345678",
    "description": "Two dresses",
    "package_size": "S",
    "weight_kg": 2,
    "delivery_mode": "STATION",
    "dest_town_id": "c3e0e7c5-7925-4c8f-8f01-f273acb9b29d",
    "origin_lat": -1.2864,
    "origin_lng": 36.8172,
    "reference": "order-1042"
  }'

json

{
  "object": "parcel",
  "livemode": false,
  "id": "parcel_test_9f3a1c72-4b8e-4d1a-9c2f-7e5b0a6d3812",
  "status": "AWAITING_DROPOFF",
  "payment_timing": "PAY_AT_PICKUP",
  "tracking_number": "TEST-GANK6F",
  "reference": "order-1042",
  "message": "Test mode — nothing was created and no payment was taken."
}

Always send X-Idempotency-Key. Derive it from your order id. If a response is lost and you retry, you get the first result back instead of a second parcel and a second charge.

4. Hear about it moving

Do not poll. Register a URL and we push each change to it, signed so you can trust it came from us.

POST/v1/webhooks

bash

curl https://api.shopinn.co.ke/api/sendway/v1/webhooks \
  -H "Authorization: Bearer sw_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myshop.co.ke/hooks/sendway",
    "events": ["parcel.delivered", "cod.settled"]
  }'

The response carries a signing secret, once. Verifying it is a few lines and it is not optional — an unsigned endpoint will accept anything anyone sends it.

Going live

Swap sw_test_ for sw_live_. Nothing else changes: same URLs, same shapes, same errors. Live keys need your account approved, which you can request from the developers page.