DELIVERIES

Update a delivery

PATCH


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

Only while the delivery is pending, dispatched or assigned. Once a courier has collected the parcel it is too late to change it, and the request is refused with not_editable.

Changing the dropoff address re-prices the delivery on your terms. An address outside the area we cover is refused with outside_service_area: cancel and book again instead. A delivery already with a courier has the change passed on to them.

REQUEST

curl -X PATCH https://roadrunnerzw.com/api/v1/deliveries/{id} \
  -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 '{
      "dropoff": {
          "instructions": "Leave with the security desk at reception"
      }
  }'

RESPONSE 200

{
    "id": "dlv_01JAV3K2QX8M4N7P",
    "object": "delivery",
    "client_reference": "ABC-10432",
    "status": "dispatched",
    "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": null,
    "cancellation_reason": null
}

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

dropoff object

Correcting where it is going. Send only the parts that change.
- name string
  
  The recipient's name, if you had it wrong.
- phone string
  
  A different number to reach them on.
- email string
  
  A different email address, or null to remove the one on file.
- address string
  
  A corrected address. Changing it after a courier is on the way may change what the delivery costs.
- instructions string
  
  New or amended instructions for the courier.
scheduled_for string

Same bound as create. Without it a client could not schedule 30 days out on POST but could on PATCH, which is the kind of difference nobody discovers until it is in production. Move the collection to a different time. ISO 8601, read as UTC, at least a minute ahead and at most seven days out.
metadata array of strings

Replaces the stored metadata outright rather than merging into it. Up to 20 key/value pairs.

Responses

200 OK

The updated delivery.

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.