Kurir.Express API

GET /v1/operator/couriers

List your couriers

Every active courier registered on the platform under your company tax id, with the vehicle, the online toggle, the last known position and the orders they are currently holding. Couriers who have not been activated by the platform are not listed: you cannot act for them either.

Responses

Example

curl https://api.kurir.express/v1/operator/couriers -H 'Authorization: Bearer kok_YOUR_KEY'

GET /v1/operator/offers

Live offers and the open pool

Two lists. offers are live, addressed offers your couriers are being asked to answer right now — the very same offers the courier app would show, with the remaining ttl_ms, not a fresh countdown. pool is the open showcase in each courier's country and dispatch radius, with courier_ids telling you which of your couriers can take each order. Answering an offer is a decision on a timer; taking from the pool is not.

Responses

Example

curl https://api.kurir.express/v1/operator/offers -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/offers/{id}/accept

Accept an offer for one of your couriers

Takes the order at the offered price, exactly as the courier tapping "Accept" would. The offer is one and the same object on both transports: if the courier answered from the app a moment earlier, you get 409 — and so would they, had you been first.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/offers/OFFER_ID/accept -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID"}' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/offers/{id}/decline

Decline an offer

The next candidate is offered the order on the same dispatch tick. Declining counts against the courier's acceptance rate exactly as it does in the app — the API is a second transport, not a second rulebook.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/offers/OFFER_ID/decline -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID"}' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/offers/{id}/counter

Name your own price for an offer

Same rule as in the app: a price at or below the platform price assigns the order to your courier immediately, a higher one goes to the customer as a bid. Services without a platform price (pallets, trucks, moves) and any cross-border pair are priced this way only.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/offers/OFFER_ID/counter -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID","price_minor":4500,"eta_pickup_min":25}' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/pool/{orderId}/claim

Take an order from the open pool

Assigns a pool order to your courier at the platform price, the same way the courier would from the showcase. The race is settled by the database, so two operators claiming the same order end with exactly one winner and one 409.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/pool/ORDER_ID/claim -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID"}' -H 'Authorization: Bearer kok_YOUR_KEY'

GET /v1/operator/orders

Orders your couriers are holding

Newest first, across the whole company. Page with cursor from next_cursor; a null next_cursor means the last page. cross_border and dropoff_country_code are here because a dispatcher decides who to send before the courier ever sees the order.

Parameters

Responses

Example

curl 'https://api.kurir.express/v1/operator/orders?status=PICKED_UP' -H 'Authorization: Bearer kok_YOUR_KEY'

GET /v1/operator/orders/{id}

Get one order

An order held by one of your couriers. An order held by someone else answers 404, not 403: we do not confirm that another company's order exists.

Parameters

Responses

Example

curl https://api.kurir.express/v1/operator/orders/ORDER_ID -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/orders/{id}/status

Move an order through its lifecycle

The same state machine, the same guards and the same side effects as the courier app: illegal transitions answer 409, FAILED requires a reason, PICKED_UP sends the recipient their delivery PIN by SMS. Delivery itself has its own endpoint (see /pod) because it needs proof.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/orders/ORDER_ID/status -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID","to":"PICKED_UP","lat":42.4304,"lng":19.2594}' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/orders/{id}/pod

Confirm delivery

Proof of delivery: either the four-digit pin the recipient received by SMS, or photo_upload_id — the key of a photo uploaded through POST /v1/uploads. Coordinates are optional: the last position you reported for that courier is used, and the country's geofence radius is checked against it exactly as it is for the app. Delivery is where the platform commission is charged.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/orders/ORDER_ID/pod -H 'Content-Type: application/json' -d '{"courier_id":"COURIER_ID","pin":"1234"}' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/operator/locations

Report courier positions

A batch of track points. Every point takes the same path as a position frame from the app: it keeps the courier present for dispatch, feeds the live map the customer watches, and refreshes "alive". This is also what puts a courier online in the first place — a courier you stop reporting for falls asleep on the same timeout as one whose phone went dark. The batch size limit is a platform setting (200 at the time of writing) and is reported in the 422 body when exceeded.

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/operator/locations -H 'Content-Type: application/json' -d '{"locations":[{"courier_id":"COURIER_ID","lat":42.4304,"lng":19.2594,"ts":1788643648000}]}' -H 'Authorization: Bearer kok_YOUR_KEY'

GET /v1/operator/ledger

Read your couriers' ledger

Platform commission charged on delivery, cash-on-delivery liabilities, top-ups and adjustments, newest first. Read-only: money is moved by people in the console, not by an integration. A positive amount grows the courier's position, a negative one shrinks it.

Parameters

Responses

Example

curl 'https://api.kurir.express/v1/operator/ledger?limit=20' -H 'Authorization: Bearer kok_YOUR_KEY'

POST /v1/partner/quotes

Quote a delivery

Returns a price and a signed quote_token valid for a few minutes. Services without a platform price (and any cross-border pair) answer 422 SERVICE_NOT_QUOTABLE with details.quoting = "bids" — create the order without a token and let couriers bid.

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/partner/quotes \
  -H 'Authorization: Bearer kek_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"service":"EXPRESS","delivery_service":"parcel","from":{"lat":42.4304,"lng":19.2594},"to":{"lat":42.4425,"lng":19.2762},"parcel":{"weight_kg":2,"fragile":false},"payment_methods":["cash"]}'

POST /v1/partner/orders

Create an order

Creates a normal Kurir.Express delivery owned by the account behind your key. Pass quote_token for a quoted service, or omit it and pass delivery_service for bidding. external_ref is your own order number: it is required and must be unique per key.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/partner/orders \
  -H 'Authorization: Bearer kek_YOUR_KEY' \
  -H 'Idempotency-Key: shop-order-1042' \
  -H 'Content-Type: application/json' \
  -d '{"external_ref":"1042","quote_token":"<from /v1/partner/quotes>","pickup":{"location":{"lat":42.4304,"lng":19.2594},"contact":{"name":"Shop","phone":"+38269000003"}},"dropoff":{"location":{"lat":42.4425,"lng":19.2762},"contact":{"name":"Ana","phone":"+38269000004"}},"parcel":{"weight_kg":2,"fragile":false},"payment_methods":["cash"]}'

GET /v1/partner/orders

List your orders

Newest first. Only orders created through this key are listed. Page with cursor from next_cursor; a null next_cursor means the last page.

Parameters

Responses

Example

curl 'https://api.kurir.express/v1/partner/orders?status=SEARCHING' -H 'Authorization: Bearer kek_YOUR_KEY'

POST /v1/partner/orders/batch

Create several orders at once

Best-effort batch: each element succeeds or fails on its own, and one bad address does not cancel the other nineteen deliveries. The response mirrors the request order. The maximum batch size is a platform setting (50 at the time of writing) and is reported in the 422 body when exceeded. Best-effort covers business errors only: a malformed element — one missing the required external_ref, say — rejects the whole request with 422, because the request itself did not parse.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/partner/orders/batch -H 'Authorization: Bearer kek_YOUR_KEY' -H 'Content-Type: application/json' -d '{"orders":[…]}'

GET /v1/partner/orders/{id}

Get one order

Full card of your order, including the courier once assigned and a freshly signed pod_photo_url (valid for 15 minutes) once the delivery is photographed. Someone else's order answers 404, not 403.

Parameters

Responses

Example

curl https://api.kurir.express/v1/partner/orders/ORDER_ID -H 'Authorization: Bearer kek_YOUR_KEY'

POST /v1/partner/orders/{id}/cancel

Cancel an order

Allowed while the order has not been handed over. The state machine decides: a delivered order answers 409 ILLEGAL_TRANSITION.

Parameters

Request body

Responses

Example

curl -X POST https://api.kurir.express/v1/partner/orders/ORDER_ID/cancel -H 'Authorization: Bearer kek_YOUR_KEY'

GET /v1/partner/orders/{id}/bids

List open bids

Courier offers for an order that has no platform price. Cheapest first; expired bids are not shown.

Parameters

Responses

Example

curl https://api.kurir.express/v1/partner/orders/ORDER_ID/bids -H 'Authorization: Bearer kek_YOUR_KEY'

POST /v1/partner/orders/{id}/bids/{bidId}/accept

Accept a bid

Assigns the courier who made this bid; the bid price becomes the order price. Losing the race to another courier answers 409 OFFER_LOST, an expired bid 409 OFFER_EXPIRED.

Parameters

Responses

Example

curl -X POST https://api.kurir.express/v1/partner/orders/ORDER_ID/bids/BID_ID/accept -H 'Authorization: Bearer kek_YOUR_KEY'

GET /v1/partner/orders/{id}/track

Track an order

Status, courier (with phone while the order is live), live position while the courier physically holds the parcel, ETAs and a short public tracking link you can forward to the recipient.

Parameters

Responses

Example

curl https://api.kurir.express/v1/partner/orders/ORDER_ID/track -H 'Authorization: Bearer kek_YOUR_KEY'

Error

Order

An order as the platform sees it. Same shape the mobile app receives.

QuoteRequest

QuoteResponse

PartnerCreateOrderRequest

Exactly one of quote_token (quoted services) or delivery_service (bidding) is required — a rule that JSON Schema cannot express, so it is enforced by the server and stated here.

WebhookEvent

Body of every webhook delivery. Which events an endpoint may subscribe to depends on the key: merchant keys get order.status, courier.assigned, bid.received, order.delivered, order.failed, order.cancelled; operator keys get offer.new, offer.result, order.update, order.cancelled_by_client, balance.low.

OperatorCouriers

OperatorOffers

OperatorOrder

OperatorOrders

OperatorLedger

OperatorOfferAnswer

OperatorCounterRequest

OperatorStatusRequest

OperatorPodRequest

Exactly one of pin or photo_upload_id is required — a rule JSON Schema cannot express, so it is enforced by the server and stated here.

OperatorLocationsRequest