DELIVERIES

Cancel a delivery

POST


                    roadrunnerzw.com/api/v1/deliveries/{id}/cancel

Permitted until the delivery reaches a terminal state. A cancellation is also sent to the courier network, so this is not merely a local status change.

REQUEST

curl -X POST https://roadrunnerzw.com/api/v1/deliveries/{id}/cancel \
  -H 'Authorization: Bearer rr_live_your_key_id' \
  -H 'X-RR-Timestamp: $(date +%s)' \
  -H 'X-RR-Signature: $SIGNATURE' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Content-Type: application/json' \
  -d '{
      "reason": "customer_cancelled",
      "note": "Customer is no longer at the address"
  }'

RESPONSE 200

{
    "id": "dlv_01JAV3K2QX8M4N7P",
    "object": "delivery",
    "client_reference": "ABC-10432",
    "status": "cancelled",
    "test_mode": false,
    "pickup": {
        "name": "ABC",
        "phone": "+263242000000",
        "address": "10 Example Avenue, Harare, Zimbabwe",
        "instructions": "Collect from the front counter"
    },
    "dropoff": {
        "name": "John Doe",
        "phone": "+263770000000",
        "email": "john@example.com",
        "address": "45 Example Road, Harare, Zimbabwe",
        "instructions": "Gate code 4471. Call on arrival."
    },
    "items": [
        {
            "name": "Widget, large",
            "quantity": 2,
            "unit_price": 1250,
            "notes": "Handle with care"
        }
    ],
    "payment_type": "prepaid",
    "cash_to_collect": null,
    "pricing": {
        "subtotal": {
            "amount": 2500,
            "currency": "USD"
        },
        "delivery_fee": {
            "amount": 500,
            "currency": "USD"
        },
        "tax": {
            "amount": 0,
            "currency": "USD"
        },
        "total": {
            "amount": 3000,
            "currency": "USD"
        }
    },
    "scheduled_for": null,
    "tracking_url": "https://staging.roadrunnerzw.com/t/8f2a9c1e4b",
    "courier": null,
    "eta": null,
    "proof_of_delivery": null,
    "created_at": "2026-09-21T14:30:00+02:00",
    "updated_at": "2026-09-21T14:30:06+02:00",
    "dispatched_at": "2026-09-21T14:30:06+02:00",
    "delivered_at": null,
    "cancelled_at": "2026-09-21T14:40:00+02:00",
    "cancellation_reason": "customer_cancelled"
}

Path

id string REQUIRED

Headers

Idempotency-Key string

Optional here. Supplying one makes the call safe to retry: the original response is returned rather than the action being repeated.

Body

reason string REQUIRED

Why it is being cancelled. We report on these, so choose the one that is true rather than the one that is easiest.

One of customer_cancelled merchant_cancelled duplicate address_problem other
note string

Anything you want on the record, especially with "other".

Responses

200 OK

The cancelled delivery. The courier network has been told as well.

401 Unauthenticated

The signature, key or timestamp did not check out. Also returned for a revoked key, and for a timestamp more than 300 seconds from ours.

403 Forbidden

The key is valid but was not issued the scope this endpoint requires. Scopes are fixed at issue, so this needs a new key rather than a retry.

404 Not found

No such delivery for this client. Deliveries are scoped to the key that created them, so another client's id reads as missing rather than forbidden.

409 Conflict

This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.

422 Validation failed

The request was understood and refused. Same envelope as every other error; details names each field at fault, so retrying unchanged will fail the same way.

429 Too many requests

Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.