Towns & coverage

Your customer chooses a town to collect from. These endpoints give you the live list — a town we open appears in your checkout without you shipping anything.

List towns

GET/v1/towns

Requires network:read.

Query	Does
`search`	Matches town, sub-county or county.
`county`	Exact county name.

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", "Bungoma"]
}

The id is what you pass as dest_town_id when quoting and booking. zone is the rate band, 1 (nearest) to 4 — useful if you show customers a rough price before they pick.

Cache this. It changes rarely, and a checkout page that fetches 80 towns on every render is slower than it needs to be. A few hours is a sensible TTL; the counties array is handy for grouping a long dropdown.

List stations

GET/v1/stations?town_id=...

The actual counters inside a town. Most integrations never need this — we route to the right station for you — but it is there if you want to show a customer exactly where they will collect.

json

{
  "object": "list",
  "data": [
    {
      "object": "station",
      "id": "8f2c...",
      "name": "Motec Phone Repairs",
      "address": "Oginga Odinga Street",
      "town": "Kisumu",
      "county": "Kisumu",
      "town_id": "fb4a416a-...",
      "latitude": -0.0917,
      "longitude": 34.768,
      "is_hub": false
    }
  ]
}

Check door delivery

POST/v1/coverage

Within Nairobi we can deliver to a door. Outside it, the parcel goes to a pickup town. This tells you which applies to a given point.

bash

curl https://api.shopinn.co.ke/api/sendway/v1/coverage \
  -H "Authorization: Bearer sw_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": -1.2864, "longitude": 36.8172}'

json

{
  "object": "coverage",
  "deliverable": true,
  "door_delivery": true,
  "message": "Door delivery is available at this address."
}

When deliverable is false, show the town picker instead of asking for a street address. Next: pricing a parcel.