POST /v1/delivery/jobs/{ref}/complete
POST /v1/delivery/jobs/{ref}/complete
| Scope | Idempotency-Key | Operation ID |
|---|---|---|
delivery.complete | Required | completeAsTenant |
Server-authoritative completion of the tenant's own delivery.
The eight steps of in one transaction: the job is locked and re-read; the caller
must be entitled to it; it must be RECEIPT_CONFIRMED (a cancelled or failed delivery is
INVALID_DELIVERY_STATE); a rider must be the active assignee; the conditional transition
to DELIVERED writes its event; the analytics fact (once per event) and the partner's
earning line (once per job, the frozen snapshot fee, in the open period) are written; the
notification goes through the outbox. A delivery already completed returns the original
result and writes nothing — no event, fact, earning or notification.
The actor is recorded as the tenant. 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}$. |
Responses
200
Completed (or completed earlier).
| 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 | |
delivered_at | string, date-time | 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.
503
Pricing/routing unavailable, request timeout, retryable contention, or an operator must act first (ACCOUNTING_PERIOD_UNAVAILABLE, outcome REQUIRES_ADMIN), or the payment provider cannot start a payment (PAYMENT_PROVIDER_UNAVAILABLE, outcome REQUIRES_PAYMENT; nothing charged).
The error envelope: code, message, detail, request_id.