Cancel, reassign and complete
All three need an Idempotency-Key, are recorded in IDM's audit log, and re-check the delivery's current state at the moment you call. A state shown in your system a moment ago is not enough.
Cancel
POST /v1/delivery/jobs/{ref}/cancel with a reason_code: an upper-case code of your own, such as CUSTOMER_REQUEST, recorded with the cancellation.
| Stage | Can you cancel? |
|---|---|
| Before a rider accepted | Yes |
| After a rider accepted, before pickup | Only if Intellisol granted your tenant late cancellation. Otherwise INVALID_DELIVERY_STATE with detail.reason: cancellation_not_permitted. |
| After pickup | No (detail.reason: after_pickup). The item is with a rider, so it goes through recovery instead. Contact the delivery company or Intellisol. |
| Already cancelled | Returns the delivery unchanged |
Cancelling withdraws live offers, releases the rider and sends delivery.cancelled.
Reassign
POST /v1/delivery/jobs/{ref}/reassign sends a delivery that is held (for example after a rider could not continue) back to dispatch. Riders and companies already excluded from it stay excluded. After pickup, or after too many re-dispatches, the delivery stays with an operator and the answer's outcome says why. Any other state is INVALID_DELIVERY_STATE.
Complete
POST /v1/delivery/jobs/{ref}/complete is for tenants whose contract lets them close their own deliveries. It works only when the recipient has already confirmed receipt (RECEIPT_CONFIRMED) and a rider is the active assignee. Completing a completed delivery returns the original answer and changes nothing.
Normally the rider completes the delivery in the Dispatch app and you only receive delivery.delivered.