The life of a job

A job is always in exactly one status. You read it as status on the job, and hear about the changes by webhook. The names are the ones delivery integrations already use, so code written for another courier provider will recognise them.

pending → searching → courier_assigned → picking_up
        → in_transit → delivered

in_transit  → returning → returned     couldn’t be handed over
until collected         → cancelled    called off
searching   → failed                   no courier in 15 minutes

Status	Meaning	Ends here?
pending	Booked, not yet offered to anyone. Scheduled jobs wait here until twenty minutes before their time.
searching	Being offered to couriers nearby. Nobody has accepted yet.
courier_assigned	A courier took it and is on the way to collect.
picking_up	The courier is at the pickup.
in_transit	Collected, and on the way to the drop-off.
delivered	Handed over, with proof.	Yes
returning	It couldn’t be handed over and is coming back to you. The courier is still working.
returned	Back on your counter. Charged like a delivery — the trip there and back was made.	Yes
cancelled	Called off before the courier collected it. Not charged.	Yes
failed	Nobody took it before the dispatch deadline — 15 minutes of searching. Not charged.	Yes

A finished job stays finished.

What you are told

Event	When
job.booked	The job is booked.
job.courier_assigned	A courier took it.
job.picked_up	The courier collected it.
job.delivered	It was handed over. Carries a summary of the proof.
job.returned	It was brought back to you. Carries the reason.
job.cancelled	It was called off. Carries the reason.
job.failed	Nobody took it in time.
job.status_changed	Our operations team put it in a status by hand — carries from, to and the reason.

searching, picking_up, in_transit and returning have no event of their own. Read the job when you need them, or treat job.picked_up as the start of in_transit.

احتیاط

A job can go back to searching after courier_assigned — when a courier has to hand it back, or our team returns it to dispatch. You will hear job.courier_assigned again when the next courier takes it.

Cancelling a booking

There is no cancel endpoint in the API today. To call a delivery off, phone our operations team: they cancel it and you receive job.cancelled. A cancelled job is not charged — the hold on your card is released.

A job can be cancelled until the courier collects it. Once it is in_transit or returning the parcel is in someone’s hands, and it is finished by delivering or returning it.