Skip to content

Shipments

Route Purpose Answer
POST /shipments Create a Shipment 201 Shipment
POST /shipments/:id/confirm Confirm a Shipment 200 Shipment
GET /shipments/:id Get a Shipment 200 Shipment
GET /shipments List Shipments 200 page of Shipments
POST /shipments/:id/cancel Cancel a Shipment 200 Shipment with offence
POST /shipments/:id/retry Retry a search 200 Shipment
POST /shipments/:id/not-received Report a Shipment not received 200 Shipment
GET /shipments/:id/events List a Shipment’s events 200 list of events
GET /shipments/:id/stream Event stream, see Live tracking Server-Sent Events

Every Shipment answer is the Shipment object. Every POST here takes an Idempotency-Key header. See Idempotency.

POST /shipments

Creates a Shipment in AWAITING_CONFIRMATION and fixes its price. Tujyane contacts no partner until you confirm it.

{
"reference": "IH-20481",
"sizeClass": "SMALL",
"pickup": {
"name": "Kacyiru Pharmacy",
"phone": "0788123456",
"addressText": "KG 7 Ave 14, Kacyiru",
"notes": "Counter 2. Ask for order IH-20481.",
"lat": -1.9367,
"lng": 30.0866
},
"recipient": {
"name": "Aline Uwase",
"phone": "+250788654321",
"addressText": "KG 11 Ave 24, Kimironko",
"notes": "Blue gate. Call on arrival.",
"lat": -1.9496,
"lng": 30.1266
},
"alternateReceiver": {
"name": "Jean Habimana",
"phone": "0788654322"
},
"parcelCount": 2
}
Field Rules
reference Required. 1 to 100 characters. Your own id. It need not be unique. The partner sees it.
sizeClass Optional, default SMALL. Only the size classes in your contract work.
pickup, recipient Required. The objects below.
pickup.name, recipient.name 1 to 120 characters.
pickup.phone, recipient.phone A Rwandan MTN or Airtel mobile number (072, 073, 078 or 079), for example 0788123456, 788123456, 250788123456 or +250788123456. Spaces, hyphens and brackets are ignored. Returned as 250788123456.
pickup.addressText, recipient.addressText 1 to 300 characters.
pickup.notes, recipient.notes Optional, up to 500 characters. The partner sees them.
lat, lng The exact point. Tujyane uses it as you send it.
alternateReceiver Optional { name, phone }: someone else who may take the parcel, for example a family member. Same rules as the Recipient’s name and phone. The partner sees it and can call this person.
parcelCount Optional, 1 to 20, default 1. How many packages the partner collects. It does not change the fee.

The Shipment, in AWAITING_CONFIRMATION. confirmBy is 30 minutes after creation. If your account uses Delivery Codes, it has the deliveryCode.

Status When
409 NO_TARIFF Your contract has no tariff for this size class.
409 CREDIT_LIMIT_EXCEEDED Live keys only. The Shipment would take you past your credit limit. See Billing and credit.
422 OUTSIDE_SERVICE_AREA Tujyane does not deliver at the pickup or the drop-off. point is pickup or dropoff.

POST /shipments/:id/confirm

Confirm when your customer has paid you. The Shipment moves to SEARCHING, and Tujyane offers it to the nearest eligible partners, one at a time. Each partner has 45 seconds to answer. No body.

Confirming a Shipment that is already confirmed returns its current state and changes nothing. With a live key, Tujyane checks your credit limit again.

Status When
409 CONFIRMATION_EXPIRED confirmBy has passed. Create a new Shipment.
409 SHIPMENT_CANCELLED The Shipment was cancelled before you confirmed it. Create a new Shipment.
409 SHIPMENT_STATE_CONFLICT The Shipment changed during your request. currentStatus says how it is now. Read it again, then retry.
409 CREDIT_LIMIT_EXCEEDED Live keys only.

GET /shipments/:id

Returns the Shipment. Use it when you reconcile, and after you reconnect to a stream.

404 when the Shipment is not yours, or belongs to the other mode.

GET /shipments

Lists the Shipments of the key’s mode, newest first.

Query Rules
limit 1 to 100, default 20.
cursor nextCursor from the previous page.
status One status.
reference Your reference, exact match.
createdFrom A full date and time with an offset, inclusive. For example 2026-11-01T00:00:00Z.
createdTo Same format, inclusive.

The filters combine. To send a + offset, URL-encode it as %2B: 2026-11-01T00:00:00%2B02:00. An unencoded + arrives as a space, and the request fails with 400.

The answer is { items, nextCursor, hasMore }. See Pagination.

POST /shipments/:id/cancel

Cancels a Shipment before the partner collects the parcel. A cancellation costs nothing.

{ "reason": "Customer cancelled the order" }

reason is optional, up to 300 characters. To cancel without a reason, send {}.

The answer is the Shipment with offence. offence is true when a partner had already accepted it, and Tujyane then records an offence against your account.

Status When
409 CANNOT_CANCEL_AFTER_PICKUP The partner has the parcel, or the Shipment is delivered or returned.
409 ILLEGAL_SHIPMENT_TRANSITION The Shipment is already cancelled or expired, or its retry window has closed. The body has from, to and actor.

POST /shipments/:id/retry

For a Shipment in NO_PARTNER_FOUND, before noPartnerDeadlineAt. Starts a new 20-minute search. No body.

Status When
409 RETRY_CLOSED The Shipment is not NO_PARTNER_FOUND, or noPartnerDeadlineAt has passed.
409 SHIPMENT_STATE_CONFLICT The Shipment changed during your request. Read it again, then retry.

POST /shipments/:id/not-received

For a DELIVERED Shipment, within 24 hours (problemReportDeadlineAt), once.

{ "note": "Customer says nobody came to the door." }

note is required, 1 to 500 characters. The Shipment stays DELIVERED, and you get shipment.not_received_reported.

Status When
409 NOT_DELIVERED The Shipment is not DELIVERED.
409 REPORT_WINDOW_CLOSED More than 24 hours have passed since delivery.
409 ALREADY_REPORTED You already reported it.

GET /shipments/:id/events

Lists the events of one Shipment, oldest first, up to 200, with the state of each webhook. Use it to find events your receiver missed. It does not include the Shipment as it was at each event. For the current state, use Get a Shipment.

{
"items": [
{
"id": "b7f6d2e8-0a9c-4e4b-9f87-2c3d4e5f6a77",
"type": "shipment.delivered",
"createdAt": "2026-11-03T08:39:48.630Z",
"webhook": {
"status": "DELIVERED",
"attempts": 1,
"lastStatusCode": 200,
"deliveredAt": "2026-11-03T08:39:49.102Z"
}
}
]
}

webhook.status is PENDING, PROCESSING, DELIVERED, FAILED, or SKIPPED (no webhook URL was set when the event happened).