Launching soon. Check your price now and join the list to be first when bookings open. Check your price

Sendway

Parcels

Booking a parcel adds it to the batch a rider will collect from you. Nothing is charged at this point.

Book a parcel

POST/v1/parcels

Requires parcels:write.

Two ways parcels leave you. By default a rider comes to you (pickup_mode: "DOOR_PICKUP") and you give coordinates. If your staff would rather walk parcels to an agent, send pickup_mode: "DROP_AT_STATION" with an origin_station_id — the origin is then taken from that point, so you send no coordinates at all. Quote the same way you book: POST /v1/quotes accepts both too, so the price you are shown is the price of the parcel you create.
FieldRequiredNotes
recipient_nameyesWho collects it.
recipient_phoneyesGets the arrival SMS and the collection PIN.
recipient_emailnoEmailed the PIN as well.
sender_phonesee notesThe number our rider calls at pickup. Required unless your SendWay account has a phone number.
sender_namenoYour shop's name, shown to the rider and the recipient. Defaults to your account name.
descriptionyesWhat is inside. Agents see this.
categorynoSTANDARD, FRAGILE, LARGE_ITEM or BULK, as in quotes.
package_sizestandard, fragileAs in quotes. Not needed for large items or bulk.
large_item, quantitylarge itemsA catalog key and how many (1 to 5).
bulk_linesbulkUnits and counts, as in quotes.
weight_kgnoSend it where you have it.
length_cm, width_cm, height_cmnoThe box size, as in quotes. Send the same values you quoted with.
is_perishablenoAs in quotes.
delivery_modeyesSTATION or DOOR.
dest_town_ideitherCollection town.
dest_lat, dest_lngeitherFor door delivery.
dest_addressnoThe delivery address as your customer typed it. Shown to the rider for door delivery.
dest_directionsnoHouse, floor or gate details for the rider, up to 120 characters.
pickup_modenoDOOR_PICKUP (default) or DROP_AT_STATION.
origin_lat, origin_lngdoorWhere a rider collects. Required for DOOR_PICKUP.
origin_station_iddrop-offThe point you hand parcels in at. Required for DROP_AT_STATION; list them with GET /v1/stations.
origin_addressnoHelps the rider find you.
origin_directionsnoFloor, shop number or landmark for the rider, up to 120 characters.
declared_valuefragile, large itemsWhat it is worth in KES. Drives cover, and is required for fragile parcels and large items.
cod_amountnoCash on delivery, in KES, up to 250,000. We collect it from your customer and credit your wallet, less a 1.5% handling fee. See pickup runs.
referencenoYour own order id. Comes back on every webhook.
json
{
  "object": "parcel",
  "livemode": true,
  "id": "9f3a1c72-4b8e-4d1a-9c2f-7e5b0a6d3812",
  "parcel_number": "PCL-A1B2C3",
  "tracking_number": "SHP-8DD1D9",
  "status": "AWAITING_PICKUP",
  "pickup_mode": "DOOR_PICKUP",
  "payment_timing": "PAY_AT_PICKUP",
  "category": "STANDARD",
  "delivery_fee": 350,
  "pickup_fee": 0,
  "cover": 0,
  "cod_amount": 0,
  "total_fee": 350,
  "currency": "KES",
  "pickup_run_id": "cbcb7d07-...",
  "reference": "order-1042",
  "message": "Booked. It will be settled with the rest of your batch when a rider collects."
}
Always send X-Idempotency-Key. Derive it from your order id — order-1042, not a random value. If the connection drops after we created the parcel, your retry returns the same parcel instead of booking and charging for a second one.

Parcel statuses

StatusMeans
AWAITING_PICKUPWaiting for a rider to collect it from you.
AWAITING_DROPOFFWaiting for you to drop it at a SendWay point.
IN_TRANSITCollected, moving through the network.
AT_PICKUP_STATIONArrived. Your customer has a PIN.
DELIVEREDCollected by your customer.
RETURNEDNot collected in time; coming back.
CANCELLEDCancelled before collection.

List your parcels

GET/v1/parcels?limit=25

Newest first, cursor-paginated. Requires parcels:read.

json
{
  "object": "list",
  "data": [{ "object": "parcel", "id": "...", "tracking_number": "SHP-8DD1D9" }],
  "has_more": true,
  "next_cursor": "9f3a1c72-4b8e-4d1a-9c2f-7e5b0a6d3812"
}

Pass next_cursor back as starting_after for the next page.

Read one

GET/v1/parcels/:id

Track by number

GET/v1/tracking/:tracking_number

Accepts either the tracking number or the parcel number. Returns status and destination without the recipient's contact details, so it is safe to render on a page your customer sees.

Cancel

POST/v1/parcels/:id/cancel

Possible while the parcel is still with you. Once a rider has scanned your batch the total is locked and you get 409 run_already_scanned — at that point the parcel is in the network and cancelling is a support conversation.

A cancelled parcel drops out of your batch, so it never becomes a charge.

Next: how you pay.