DELIVERIES

Fetch a delivery

GET


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

Accepts either a Road Runner delivery id (dlv_…) or your own client_reference, so you need not store our id at all.

Supports ETag / If-None-Match: send the previous ETag and receive 304 Not Modified when nothing has changed. Use this when polling.

REQUEST

curl -X GET 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'

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

Responses

200 OK

The current state of the 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.

429 Too many requests

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