POST /v1/delivery/jobs/{ref}/cancel
POST /v1/delivery/jobs/{ref}/cancel
| Scope | Idempotency-Key | Operation ID |
|---|---|---|
delivery.cancel | Required | cancelJob |
Cancel at a permitted stage, with a reason.
Freely before a rider accepted the delivery; after assignment only where the platform
granted the tenant that policy (cancel_after_assignment), else INVALID_DELIVERY_STATE
with detail.reason: cancellation_not_permitted; after handover never — that is recovery
(detail.reason: after_pickup). Live offers are cancelled, the rider released, the job
CANCELLED and delivery.cancelled sent. Cancelling a cancelled delivery returns it
unchanged. The reason is a code. Idempotency-Key required. Audited.
Request
Signed with your API credential: see Authentication.
| Parameter | In | Required | Description |
|---|---|---|---|
Idempotency-Key | header | Yes | One key per user intent, reused for every retry of that intent. See Idempotency. |
ref | path | Yes | Public reference of a delivery job or Bulk child. Pattern ^DX-[0-9A-HJKMNP-TV-Z]{8}$. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
reason_code | string | Yes | Pattern ^[A-Z][A-Z0-9_]{1,40}$. |
Responses
200
Where the delivery now stands.
| Field | Type | Required | Description |
|---|---|---|---|
delivery_reference | string | Yes | Public reference of a delivery job or Bulk child. Pattern ^DX-[0-9A-HJKMNP-TV-Z]{8}$. |
status | string | Yes | One of: PENDING_DELIVERY, DELIVERY_REQUESTED, OFFERED, ASSIGNED, ARRIVED_AT_PICKUP, PICKED_UP, ON_THE_WAY, ARRIVED_AT_DESTINATION, RECEIPT_CONFIRMED, DELIVERED, CANCELLED, FAILED, DELIVERY_EXCEPTION, RECOVERY_REQUIRED. |
customer_status | string | Yes | |
outcome | object or null | Yes | The P9 outcome when set — a hold for an operator (REQUIRES_ADMIN with CUSTODY_HELD or REPEATED_RECOVERY_FAILURE) or how the delivery ended. |
outcome.code | string | Yes | |
outcome.reason | string | Yes |
400
Structural validation failed or an Idempotency-Key is missing.
The error envelope: code, message, detail, request_id.
401
Unknown, revoked or wrong-environment credential, bad signature, or expired session.
The error envelope: code, message, detail, request_id.
403
Tenant access denied (existence is not disclosed), insufficient scope, MFA/step-up required, partner blocked or module disabled.
The error envelope: code, message, detail, request_id.
409
State changed, race lost, or idempotency conflict. Refetch before deciding again.
The error envelope: code, message, detail, request_id.
422
Semantically invalid (location, vehicle, server-controlled field, bulk limits).
The error envelope: code, message, detail, request_id.
429
Rate limit reached; honour Retry-After.
The error envelope: code, message, detail, request_id.
500
Unexpected failure. Only code and request_id are returned.
The error envelope: code, message, detail, request_id.