{ "openapi": "3.1.0", "info": { "title": "Road Runner", "version": "1.0.0", "description": "Dispatch and track deliveries through Road Runner.\n\nThis reference is generated from the running code, so it cannot drift from the\nAPI you are calling.\n\n---\n\n## Quick start\n\n1. Road Runner issues you a **key id** (`rr_live_\u2026`) and a **secret**\n (`rrsk_\u2026`). The secret is shown once and cannot be retrieved again.\n2. Sign every request (below) and call `GET /v1/ping` to confirm the key works.\n3. `POST /v1/deliveries` to dispatch. You get `202 Accepted` with a `pending`\n delivery.\n4. Register a webhook endpoint and call `POST /v1/webhooks/{id}/test` to prove\n your handler works **before** real deliveries depend on it.\n\n---\n\n## Authentication\n\nEvery request carries three headers:\n\n```\nAuthorization: Bearer rr_live_EXAMPLEKEYID0000000000000\nX-RR-Timestamp: 1790000000\nX-RR-Signature: 8c7f2a...\n```\n\n### Building the signature\n\n```\nsigning_string = key_id + \".\" + timestamp + \".\" + METHOD + \".\" + host + path\n + \".\" + sha256_hex(raw_body)\n\nsignature = hmac_sha256(secret, signing_string) // lowercase hex\n```\n\n**Three details that trip people up:**\n\n| | |\n|---|---|\n| `host` | Hostname **without** the port. `staging.roadrunnerzw.com`, not `\u2026:443` |\n| `path` | Includes the `/api/v1` prefix **and** the query string |\n| `raw_body` | The exact bytes you send. An empty body hashes the **empty string**, not `{}` or `[]` |\n\nThe key id and host are part of the signing string deliberately: a signature\nminted for staging cannot be replayed against production.\n\n### Worked example\n\n```\nkey_id rr_live_ABC\ntimestamp 1790000000\nmethod POST\nhost staging.roadrunnerzw.com\npath /api/v1/deliveries\nbody {\"a\":1}\n\nsigning_string:\nrr_live_ABC.1790000000.POST.staging.roadrunnerzw.com/api/v1/deliveries.\n```\n\n### Code\n\n**PHP**\n\n```php\n$ts = (string) time();\n$body = json_encode($payload, JSON_UNESCAPED_SLASHES);\n$sig = hash_hmac('sha256',\n \"{$keyId}.{$ts}.POST.staging.roadrunnerzw.com/api/v1/deliveries.\"\n . hash('sha256', $body),\n $secret);\n```\n\n**Node**\n\n```js\nconst ts = Math.floor(Date.now() / 1000).toString();\nconst body = JSON.stringify(payload);\nconst hash = crypto.createHash('sha256').update(body).digest('hex');\nconst sig = crypto.createHmac('sha256', secret)\n .update(`${keyId}.${ts}.POST.staging.roadrunnerzw.com/api/v1/deliveries.${hash}`)\n .digest('hex');\n```\n\n**Python**\n\n```python\nts = str(int(time.time()))\nbody = json.dumps(payload, separators=(\",\", \":\"))\nh = hashlib.sha256(body.encode()).hexdigest()\nsig = hmac.new(secret.encode(),\n f\"{key_id}.{ts}.POST.staging.roadrunnerzw.com/api/v1/deliveries.{h}\".encode(),\n hashlib.sha256).hexdigest()\n```\n\n**bash**\n\n```bash\nBODY_HASH=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hex | awk '{print $NF}')\nSIG=$(printf '%s' \"$KEY.$TS.POST.$HOST$PATH.$BODY_HASH\" \\\n | openssl dgst -sha256 -hmac \"$SECRET\" -hex | awk '{print $NF}')\n```\n\n### Validation rules\n\nA request is refused unless all hold:\n\n- the key exists, is not revoked and has not expired\n- the timestamp is within **300 seconds** of ours: compare against\n `server_time` from `GET /v1/ping` if you suspect clock drift\n- the signature matches\n- that signature has not been used before\n- the key has the scope the endpoint requires\n\n### Scopes\n\n| Scope | Grants |\n|---|---|\n| `deliveries:read` | Listing and fetching deliveries |\n| `deliveries:write` | Creating and editing deliveries |\n| `deliveries:cancel` | Cancelling a delivery |\n| `quotes:write` | Requesting quotes |\n| `webhooks:manage` | Managing webhook endpoints |\n\nCancelling is kept apart from `deliveries:write` on purpose, so an\nintegration that only books deliveries cannot also cancel them. A key missing\nthe scope an endpoint needs is refused with `403 insufficient_scope`, naming\nthe scope it wanted.\n\nAsk us if a key needs a permission it does not have. We can change what an\nexisting key may do without reissuing it, so there is no new secret to copy\nand nothing to swap in your integration.\n\n---\n\n## Idempotency\n\n`POST /v1/deliveries` **requires** an `Idempotency-Key` header. Use your own\norder reference.\n\n```\nIdempotency-Key: order-10432\n```\n\n| Situation | Result |\n|---|---|\n| New key | Processed normally |\n| Same key, same body | Original response replayed, `Idempotency-Replayed: true` |\n| Same key, **different** body | `409 idempotency_key_reuse` |\n| Same key, original still running | `409 idempotency_in_progress` |\n\nKeys are scoped to you and retained 24 hours.\n\n**Retries must be re-signed.** A byte-identical resend: same timestamp, same\nsignature: is refused as `signature_replayed` and never reaches the\nidempotency layer. Generate a fresh timestamp and signature for each attempt\nand keep the same `Idempotency-Key`. That key is what makes the retry safe,\nnot the signature.\n\n---\n\n## Errors\n\nEvery non-2xx response uses one envelope:\n\n```json\n{\n \"error\": {\n \"type\": \"validation_error\",\n \"code\": \"address_not_zimbabwean\",\n \"message\": \"We only deliver within Zimbabwe.\",\n \"details\": [{ \"field\": \"dropoff.address\", \"issue\": \"unserviceable\" }],\n \"request_id\": \"req_01JAV3K2QX8M4N7P\"\n }\n}\n```\n\n`type` is a small stable set you can branch on. `code` is specific.\n`request_id` is also returned in the `X-Request-Id` header: quote it to us.\n\n| `type` | HTTP | Meaning |\n|---|---|---|\n| `authentication_error` | 401 | Key, signature or timestamp problem |\n| `permission_error` | 403 | Valid key, missing scope |\n| `not_found` | 404 | Unknown resource, or one that is not yours |\n| `validation_error` | 422 | Understood, contents rejected |\n| `conflict` | 409 | Idempotency clash or illegal state change |\n| `rate_limit_error` | 429 | Too many requests; see `Retry-After` |\n| `provider_error` | 502 | Courier network rejected or unreachable |\n| `server_error` | 500 | Our fault: send us the `request_id` |\n\nA delivery belonging to another client returns **404, never 403**.\n\n---\n\n## Webhooks\n\nRegister an endpoint with `POST /v1/webhooks`. The response contains a\n`secret`, shown once.\n\n### Verifying what we send\n\n```\nX-RR-Event: delivery.delivered\nX-RR-Event-Id: evt_01JAV3K2QX8M4N7P\nX-RR-Timestamp: 1790000000\nX-RR-Signature: 3d9e7b...\n```\n\n```\nexpected = hmac_sha256(secret, timestamp + \".\" + sha256_hex(raw_body))\n```\n\nCompare in constant time and reject anything older than five minutes.\n\n**`X-RR-Signature` may contain more than one signature, comma separated.**\nAccept the message if **any** of them matches:\n\n```\nX-RR-Signature: 3d9e7b...,a1c4f8...\n```\n\nThis is how a secret is rotated without breaking you. When you rotate, we sign\nwith both the new secret and the previous one for seven days, so your endpoint\nkeeps working whether or not you have deployed the new value yet: deploy when\nit suits you, not when we say so.\n\nDay to day there is exactly one signature and no comma. Split on the comma\nanyway: a verifier that compares the whole header exactly will pass every test\nyou run and then fail the first time a secret is rotated.\n\n```php\n$expected = hash_hmac('sha256', $timestamp.'.'.hash('sha256', $rawBody), $secret);\n\n$ok = false;\nforeach (explode(',', $header) as $candidate) {\n $ok = hash_equals($expected, trim($candidate)) || $ok; // no early return\n}\n```\n\nTo rotate: `POST /v1/webhooks/{id}/rotate`. The response carries the new secret\nonce, and the date the previous one stops being accepted.\n\n### Events\n\n`delivery.created` \u00b7 `delivery.dispatched` \u00b7 `delivery.dispatch_failed` \u00b7\n`delivery.assigned` \u00b7 `delivery.picked_up` \u00b7 `delivery.in_transit` \u00b7\n`delivery.delivered` \u00b7 `delivery.failed` \u00b7 `delivery.cancelled`\n\n### What to expect\n\n- **At least once.** Deduplicate on `X-RR-Event-Id`.\n- **Not ordered.** Each payload carries the full delivery with `updated_at`;\n ignore anything older than what you hold.\n- **Statuses can move backwards**: an unassigned courier returns `assigned` to\n `dispatched`. Do not assume monotonic progress.\n- Answer **2xx within 10 seconds**. Acknowledge first, work afterwards.\n- We retry 8 times over ~24 hours. An endpoint failing for 48 hours is\n disabled and you are notified.\n\nWebhooks are a convenience, never the sole source of truth. If you have heard\nnothing, poll `GET /v1/deliveries/{id}`.\n\n---\n\n## Conventions\n\n| | |\n|---|---|\n| **Money** | Integer minor units with an explicit currency. `{\"amount\": 350, \"currency\": \"USD\"}` is $3.50 |\n| **Phones** | E.164. `+263770000000`. Recipient numbers must be Zimbabwean |\n| **Timestamps** | RFC 3339 with offset. `2026-09-21T14:30:00+02:00` |\n| **Ids** | Prefixed: `dlv_` delivery, `evt_` event, `whk_` webhook, `req_` request |\n| **Paging** | Cursor-based. Pass `next_cursor` from the previous page |\n| **Service area** | Zimbabwe only, and the recipient phone must be Zimbabwean |\n\n## Rate limits\n\n120 writes/min and 600 reads/min per client. Every response carries\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. A `429`\nadds `Retry-After`.\n" }, "servers": [ { "url": "https://roadrunnerzw.com/api" } ], "security": [ { "keyId": [], "timestamp": [], "signature": [] } ], "paths": { "/v1/deliveries": { "get": { "operationId": "v1.deliveries.index", "description": "Returns your deliveries, newest first. Filter with `status` (repeatable),\n`client_reference`, `created_after` and `created_before`. Paging is by\ncursor: pass the `next_cursor` from the previous page.", "summary": "List deliveries", "tags": [ "Delivery" ], "responses": { "200": { "description": "A cursor-paginated page of your deliveries, newest first.\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"dlv_01JAV3K2QX8M4N7P\",\n \"object\": \"delivery\",\n \"client_reference\": \"ABC-10432\",\n \"status\": \"dispatched\",\n \"test_mode\": false,\n \"pickup\": {\n \"name\": \"ABC\",\n \"phone\": \"+263242000000\",\n \"address\": \"10 Example Avenue, Harare, Zimbabwe\",\n \"instructions\": \"Collect from the front counter\"\n },\n \"dropoff\": {\n \"name\": \"John Doe\",\n \"phone\": \"+263770000000\",\n \"email\": \"john@example.com\",\n \"address\": \"45 Example Road, Harare, Zimbabwe\",\n \"instructions\": \"Gate code 4471. Call on arrival.\"\n },\n \"items\": [\n {\n \"name\": \"Widget, large\",\n \"quantity\": 2,\n \"unit_price\": 1250,\n \"notes\": \"Handle with care\"\n }\n ],\n \"payment_type\": \"prepaid\",\n \"cash_to_collect\": null,\n \"pricing\": {\n \"subtotal\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"delivery_fee\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"total\": {\n \"amount\": 3000,\n \"currency\": \"USD\"\n }\n },\n \"scheduled_for\": null,\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": null,\n \"eta\": null,\n \"proof_of_delivery\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"updated_at\": \"2026-09-21T14:30:06+02:00\",\n \"dispatched_at\": \"2026-09-21T14:30:06+02:00\",\n \"delivered_at\": null,\n \"cancelled_at\": null,\n \"cancellation_reason\": null\n }\n ],\n \"has_more\": false,\n \"next_cursor\": null\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "object": "list", "data": [ { "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 } ], "has_more": false, "next_cursor": null } ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] }, "post": { "operationId": "v1.deliveries.store", "description": "The delivery is accepted immediately and sent to a courier network in\nthe background, so the response is `202 Accepted` with a `pending`\ndelivery rather than `201 Created`. Watch for the `delivery.dispatched`\nor `delivery.dispatch_failed` webhook, or poll this delivery, to learn\nthe outcome.\n\nAn `Idempotency-Key` header is required: retrying with the same key\nreturns the original response instead of creating a second delivery.", "summary": "Create a delivery", "tags": [ "Delivery" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "REQUIRED. A unique string of your choosing, at most 255 characters: a UUID is the usual choice. Retrying with the same key returns the original response instead of creating a second delivery, so reuse it on every retry of the same intent and change it for a new one. Reusing a key with a different body returns 409.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeliveryRequest" } } } }, "responses": { "202": { "description": "Accepted and queued. The delivery exists with status `pending`; a courier has not been assigned yet.\n\n```json\n{\n \"id\": \"dlv_01JAV3K2QX8M4N7P\",\n \"object\": \"delivery\",\n \"client_reference\": \"ABC-10432\",\n \"status\": \"pending\",\n \"test_mode\": false,\n \"pickup\": {\n \"name\": \"ABC\",\n \"phone\": \"+263242000000\",\n \"address\": \"10 Example Avenue, Harare, Zimbabwe\",\n \"instructions\": \"Collect from the front counter\"\n },\n \"dropoff\": {\n \"name\": \"John Doe\",\n \"phone\": \"+263770000000\",\n \"email\": \"john@example.com\",\n \"address\": \"45 Example Road, Harare, Zimbabwe\",\n \"instructions\": \"Gate code 4471. Call on arrival.\"\n },\n \"items\": [\n {\n \"name\": \"Widget, large\",\n \"quantity\": 2,\n \"unit_price\": 1250,\n \"notes\": \"Handle with care\"\n }\n ],\n \"payment_type\": \"prepaid\",\n \"cash_to_collect\": null,\n \"pricing\": {\n \"subtotal\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"delivery_fee\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"total\": {\n \"amount\": 3000,\n \"currency\": \"USD\"\n }\n },\n \"scheduled_for\": null,\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": null,\n \"eta\": null,\n \"proof_of_delivery\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"updated_at\": \"2026-09-21T14:30:06+02:00\",\n \"dispatched_at\": null,\n \"delivered_at\": null,\n \"cancelled_at\": null,\n \"cancellation_reason\": null\n}\n```", "content": { "application/json": { "schema": { "examples": [ { "id": "dlv_01JAV3K2QX8M4N7P", "object": "delivery", "client_reference": "ABC-10432", "status": "pending", "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": null, "delivered_at": null, "cancelled_at": null, "cancellation_reason": null } ], "$ref": "#/components/schemas/DeliveryResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "conflict", "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/deliveries/{id}": { "get": { "operationId": "v1.deliveries.show", "description": "Accepts either a Road Runner delivery id (`dlv_\u2026`) or your own\n`client_reference`, so you need not store our id at all.\n\nSupports `ETag` / `If-None-Match`: send the previous `ETag` and receive\n`304 Not Modified` when nothing has changed. Use this when polling.", "summary": "Fetch a delivery", "tags": [ "Delivery" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current state of the delivery.\n\n```json\n{\n \"id\": \"dlv_01JAV3K2QX8M4N7P\",\n \"object\": \"delivery\",\n \"client_reference\": \"ABC-10432\",\n \"status\": \"dispatched\",\n \"test_mode\": false,\n \"pickup\": {\n \"name\": \"ABC\",\n \"phone\": \"+263242000000\",\n \"address\": \"10 Example Avenue, Harare, Zimbabwe\",\n \"instructions\": \"Collect from the front counter\"\n },\n \"dropoff\": {\n \"name\": \"John Doe\",\n \"phone\": \"+263770000000\",\n \"email\": \"john@example.com\",\n \"address\": \"45 Example Road, Harare, Zimbabwe\",\n \"instructions\": \"Gate code 4471. Call on arrival.\"\n },\n \"items\": [\n {\n \"name\": \"Widget, large\",\n \"quantity\": 2,\n \"unit_price\": 1250,\n \"notes\": \"Handle with care\"\n }\n ],\n \"payment_type\": \"prepaid\",\n \"cash_to_collect\": null,\n \"pricing\": {\n \"subtotal\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"delivery_fee\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"total\": {\n \"amount\": 3000,\n \"currency\": \"USD\"\n }\n },\n \"scheduled_for\": null,\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": null,\n \"eta\": null,\n \"proof_of_delivery\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"updated_at\": \"2026-09-21T14:30:06+02:00\",\n \"dispatched_at\": \"2026-09-21T14:30:06+02:00\",\n \"delivered_at\": null,\n \"cancelled_at\": null,\n \"cancellation_reason\": null\n}\n```", "content": { "application/json": { "schema": { "examples": [ { "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 } ], "$ref": "#/components/schemas/DeliveryResource" } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] }, "patch": { "operationId": "v1.deliveries.update", "description": "Only while the delivery is `pending`, `dispatched` or `assigned`. Once\na courier has collected the parcel it is too late to change it, and the\nrequest is refused with `not_editable`.\n\nChanging the dropoff address re-prices the delivery on your terms. An\naddress outside the area we cover is refused with\n`outside_service_area`: cancel and book again instead. A delivery\nalready with a courier has the change passed on to them.", "summary": "Update a delivery", "tags": [ "Delivery" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional here. Supplying one makes the call safe to retry: the original response is returned rather than the action being repeated.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeliveryRequest" } } } }, "responses": { "200": { "description": "The updated delivery.\n\n```json\n{\n \"id\": \"dlv_01JAV3K2QX8M4N7P\",\n \"object\": \"delivery\",\n \"client_reference\": \"ABC-10432\",\n \"status\": \"dispatched\",\n \"test_mode\": false,\n \"pickup\": {\n \"name\": \"ABC\",\n \"phone\": \"+263242000000\",\n \"address\": \"10 Example Avenue, Harare, Zimbabwe\",\n \"instructions\": \"Collect from the front counter\"\n },\n \"dropoff\": {\n \"name\": \"John Doe\",\n \"phone\": \"+263770000000\",\n \"email\": \"john@example.com\",\n \"address\": \"45 Example Road, Harare, Zimbabwe\",\n \"instructions\": \"Gate code 4471. Call on arrival.\"\n },\n \"items\": [\n {\n \"name\": \"Widget, large\",\n \"quantity\": 2,\n \"unit_price\": 1250,\n \"notes\": \"Handle with care\"\n }\n ],\n \"payment_type\": \"prepaid\",\n \"cash_to_collect\": null,\n \"pricing\": {\n \"subtotal\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"delivery_fee\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"total\": {\n \"amount\": 3000,\n \"currency\": \"USD\"\n }\n },\n \"scheduled_for\": null,\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": null,\n \"eta\": null,\n \"proof_of_delivery\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"updated_at\": \"2026-09-21T14:30:06+02:00\",\n \"dispatched_at\": \"2026-09-21T14:30:06+02:00\",\n \"delivered_at\": null,\n \"cancelled_at\": null,\n \"cancellation_reason\": null\n}\n```", "content": { "application/json": { "schema": { "examples": [ { "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 } ], "$ref": "#/components/schemas/DeliveryResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "conflict", "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/deliveries/{id}/tracking": { "get": { "operationId": "v1.deliveries.tracking", "description": "The current status, the courier when one is assigned, and a customer\ntracking link you can pass straight to the recipient.", "summary": "Track a delivery", "tags": [ "Delivery" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current status and a tracking link you can give the recipient.\n\n```json\n{\n \"status\": \"in_transit\",\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": {\n \"name\": \"Jane S.\"\n },\n \"eta\": null,\n \"updated_at\": \"2026-09-21T14:48:00+02:00\"\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "status": "in_transit", "tracking_url": "https://staging.roadrunnerzw.com/t/8f2a9c1e4b", "courier": { "name": "Jane S." }, "eta": null, "updated_at": "2026-09-21T14:48:00+02:00" } ], "properties": { "status": { "type": "string" }, "tracking_url": { "type": "string" }, "courier": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "eta": { "type": "null" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "status", "tracking_url", "courier", "eta", "updated_at" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/deliveries/{id}/events": { "get": { "operationId": "v1.deliveries.events", "description": "Every status change in order, with where it came from. This is the\nrecord to quote in a dispute: it is append-only and nothing overwrites\nan earlier entry.", "summary": "Delivery history", "tags": [ "Delivery" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every status change in order, with where each came from.\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"evt_01JAV3K2QX8M4N7A\",\n \"object\": \"delivery_event\",\n \"type\": \"delivery.created\",\n \"status\": \"pending\",\n \"occurred_at\": \"2026-09-21T14:30:00+02:00\",\n \"source\": \"api\",\n \"data\": null\n },\n {\n \"id\": \"evt_01JAV3K2QX8M4N7B\",\n \"object\": \"delivery_event\",\n \"type\": \"delivery.dispatched\",\n \"status\": \"dispatched\",\n \"occurred_at\": \"2026-09-21T14:30:06+02:00\",\n \"source\": \"system\",\n \"data\": null\n },\n {\n \"id\": \"evt_01JAV3K2QX8M4N7C\",\n \"object\": \"delivery_event\",\n \"type\": \"delivery.in_transit\",\n \"status\": \"in_transit\",\n \"occurred_at\": \"2026-09-21T14:48:00+02:00\",\n \"source\": \"provider\",\n \"data\": {\n \"courier_name\": \"Jane S.\"\n }\n }\n ],\n \"has_more\": false\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "object": "list", "data": [ { "id": "evt_01JAV3K2QX8M4N7A", "object": "delivery_event", "type": "delivery.created", "status": "pending", "occurred_at": "2026-09-21T14:30:00+02:00", "source": "api", "data": null }, { "id": "evt_01JAV3K2QX8M4N7B", "object": "delivery_event", "type": "delivery.dispatched", "status": "dispatched", "occurred_at": "2026-09-21T14:30:06+02:00", "source": "system", "data": null }, { "id": "evt_01JAV3K2QX8M4N7C", "object": "delivery_event", "type": "delivery.in_transit", "status": "in_transit", "occurred_at": "2026-09-21T14:48:00+02:00", "source": "provider", "data": { "courier_name": "Jane S." } } ], "has_more": false } ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/deliveries/{id}/cancel": { "post": { "operationId": "v1.deliveries.cancel", "description": "Permitted until the delivery reaches a terminal state. A cancellation\nis also sent to the courier network, so this is not merely a local\nstatus change.", "summary": "Cancel a delivery", "tags": [ "Delivery" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional here. Supplying one makes the call safe to retry: the original response is returned rather than the action being repeated.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "examples": [ { "reason": "customer_cancelled", "note": "Customer is no longer at the address" } ], "properties": { "reason": { "type": "string", "description": "Why it is being cancelled. We report on these, so choose the\none that is true rather than the one that is easiest.", "enum": [ "customer_cancelled", "merchant_cancelled", "duplicate", "address_problem", "other" ] }, "note": { "type": [ "string", "null" ], "description": "Anything you want on the record, especially with \"other\".", "maxLength": 500 } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "The cancelled delivery. The courier network has been told as well.\n\n```json\n{\n \"id\": \"dlv_01JAV3K2QX8M4N7P\",\n \"object\": \"delivery\",\n \"client_reference\": \"ABC-10432\",\n \"status\": \"cancelled\",\n \"test_mode\": false,\n \"pickup\": {\n \"name\": \"ABC\",\n \"phone\": \"+263242000000\",\n \"address\": \"10 Example Avenue, Harare, Zimbabwe\",\n \"instructions\": \"Collect from the front counter\"\n },\n \"dropoff\": {\n \"name\": \"John Doe\",\n \"phone\": \"+263770000000\",\n \"email\": \"john@example.com\",\n \"address\": \"45 Example Road, Harare, Zimbabwe\",\n \"instructions\": \"Gate code 4471. Call on arrival.\"\n },\n \"items\": [\n {\n \"name\": \"Widget, large\",\n \"quantity\": 2,\n \"unit_price\": 1250,\n \"notes\": \"Handle with care\"\n }\n ],\n \"payment_type\": \"prepaid\",\n \"cash_to_collect\": null,\n \"pricing\": {\n \"subtotal\": {\n \"amount\": 2500,\n \"currency\": \"USD\"\n },\n \"delivery_fee\": {\n \"amount\": 500,\n \"currency\": \"USD\"\n },\n \"tax\": {\n \"amount\": 0,\n \"currency\": \"USD\"\n },\n \"total\": {\n \"amount\": 3000,\n \"currency\": \"USD\"\n }\n },\n \"scheduled_for\": null,\n \"tracking_url\": \"https://staging.roadrunnerzw.com/t/8f2a9c1e4b\",\n \"courier\": null,\n \"eta\": null,\n \"proof_of_delivery\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"updated_at\": \"2026-09-21T14:30:06+02:00\",\n \"dispatched_at\": \"2026-09-21T14:30:06+02:00\",\n \"delivered_at\": null,\n \"cancelled_at\": \"2026-09-21T14:40:00+02:00\",\n \"cancellation_reason\": \"customer_cancelled\"\n}\n```", "content": { "application/json": { "schema": { "examples": [ { "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" } ], "$ref": "#/components/schemas/DeliveryResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "conflict", "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used with a different request body. Reuse a key only when retrying the same intent.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/pickup-locations": { "get": { "operationId": "v1.pickup-locations.index", "description": "The places your parcels are collected from, saved in the portal. Pass a\nlocation's `id` as `pickup_location` when quoting or booking. The one\nwith `is_default: true` is used when a booking names no pickup.", "summary": "List pickup locations", "tags": [ "PickupLocation" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "string" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/ping": { "get": { "operationId": "v1.ping", "description": "Confirms the API key works and reports the client it belongs to, its\nscopes, and whether it is a test key.\n\n`server_time` is the quickest way to diagnose a signing problem: if your\nclock differs from ours by more than 300 seconds, every signed request\nfails with `timestamp_out_of_range`.", "summary": "Check your credentials", "tags": [ "Ping" ], "responses": { "200": { "description": "The key is valid. Shows the client it belongs to and what it may do.\n\n```json\n{\n \"ok\": true,\n \"client\": \"ABC\",\n \"key_id\": \"rr_live_EXAMPLEKEYID0000000000000\",\n \"scopes\": [\n \"deliveries:read\",\n \"deliveries:write\",\n \"webhooks:manage\"\n ],\n \"test_mode\": false,\n \"server_time\": \"2026-09-21T14:30:00+02:00\"\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "ok": true, "client": "ABC", "key_id": "rr_live_EXAMPLEKEYID0000000000000", "scopes": [ "deliveries:read", "deliveries:write", "webhooks:manage" ], "test_mode": false, "server_time": "2026-09-21T14:30:00+02:00" } ], "properties": { "ok": { "type": "boolean" }, "client": { "type": "string" }, "key_id": { "type": "string" }, "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "test_mode": { "type": "string" }, "server_time": { "type": "string" } }, "required": [ "ok", "client", "key_id", "scopes", "test_mode", "server_time" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/quotes": { "post": { "operationId": "v1.quotes.store", "description": "Prices a trip and confirms we will deliver to it, before you commit.\n\nPass the returned `id` as `quote_id` when creating the delivery to lock\nthis fee. Quotes expire after 15 minutes and may be used once.\n\nAn unserviceable address is returned as an error rather than a quote\nwith a flag, because an error is harder to ignore.", "summary": "Quote a delivery", "tags": [ "Quote" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "examples": [ { "pickup": { "address": "10 Example Avenue, Harare, Zimbabwe" }, "dropoff": { "address": "45 Example Road, Harare, Zimbabwe", "phone": "+263770000000" }, "items_value": 2500 } ], "properties": { "pickup": { "type": "object", "description": "Where it would be collected. Leave it out and we use the\npickup address held on your account.", "properties": { "address": { "type": "string", "description": "Street address including the suburb.", "maxLength": 512 } } }, "pickup_location": { "type": [ "string", "null" ], "description": "A saved pickup location by id (pl_\u2026), instead of `pickup`.", "maxLength": 40 }, "dropoff": { "type": "object", "description": "Where it would be going. This is what the price is measured to.", "properties": { "address": { "type": "string", "description": "Street address including the suburb. The more exact it is, the\ncloser the quote is to what you will be charged.", "maxLength": 512 }, "phone": { "type": [ "string", "null" ], "description": "The recipient's number, if you have it. We check it is\nZimbabwean, so a quote fails here rather than at booking.", "maxLength": 32 }, "country": { "type": [ "string", "null" ], "description": "Defaults to Zimbabwe. We deliver inside Zimbabwe only.", "maxLength": 64 } }, "required": [ "address" ] }, "items_value": { "type": [ "integer", "null" ], "description": "What the goods are worth, in cents. Some accounts waive the\ndelivery fee above a basket value; this is how we know.", "minimum": 0 }, "service_level": { "type": [ "string", "null" ], "description": "How fast you need it: `standard`, `express` or `scheduled`.\nExpress costs more and scheduled can cost less; what your\naccount pays for each is on your profile page.", "enum": [ "standard", "express", "scheduled", null ] }, "cash_to_collect": { "type": [ "integer", "null" ], "description": "Cash the courier will collect on delivery, in cents. Some\naccounts carry a handling fee on this, so leaving it out of a\nquote makes the quote lower than the booking.", "minimum": 0 } }, "required": [ "dropoff" ] } } } }, "responses": { "201": { "description": "A price for this trip. Pass `id` as `quote_id` when creating the delivery to lock it. Expires after 15 minutes and may be used once.\n\n```json\n{\n \"id\": \"qte_01JAV3K2QX8M4N7P\",\n \"object\": \"quote\",\n \"serviceable\": true,\n \"pricing_mode\": \"per_km\",\n \"distance_metres\": 15400,\n \"delivery_fee\": {\n \"amount\": 1540,\n \"currency\": \"USD\"\n },\n \"fee_reason\": \"per_km\",\n \"expires_at\": \"2026-09-21T14:45:00+02:00\"\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "id": "qte_01JAV3K2QX8M4N7P", "object": "quote", "serviceable": true, "pricing_mode": "per_km", "distance_metres": 15400, "delivery_fee": { "amount": 1540, "currency": "USD" }, "fee_reason": "per_km", "expires_at": "2026-09-21T14:45:00+02:00" } ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "quote" }, "serviceable": { "type": "boolean" }, "pricing_mode": { "type": "string" }, "distance_metres": { "type": [ "integer", "null" ] }, "delivery_fee": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "fee_reason": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "object", "serviceable", "pricing_mode", "distance_metres", "delivery_fee", "fee_reason", "expires_at" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/webhooks": { "get": { "operationId": "v1.webhooks.index", "description": "Returns your registered endpoints with their subscribed events and\nrecent delivery health. Secrets are never returned.", "summary": "List webhook endpoints", "tags": [ "Webhooks", "Webhook" ], "responses": { "200": { "description": "Your registered webhook endpoints and their recent health.\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"whk_01JAV3K2QX8M4N7P\",\n \"object\": \"webhook_endpoint\",\n \"url\": \"https://example.com/hooks/roadrunner\",\n \"events\": [\n \"delivery.dispatched\",\n \"delivery.delivered\"\n ],\n \"active\": true,\n \"consecutive_failures\": 0,\n \"last_success_at\": \"2026-09-21T14:31:00+02:00\",\n \"disabled_at\": null,\n \"created_at\": \"2026-09-20T09:00:00+02:00\"\n }\n ]\n}\n```", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "object": "list", "data": [ { "id": "whk_01JAV3K2QX8M4N7P", "object": "webhook_endpoint", "url": "https://example.com/hooks/roadrunner", "events": [ "delivery.dispatched", "delivery.delivered" ], "active": true, "consecutive_failures": 0, "last_success_at": "2026-09-21T14:31:00+02:00", "disabled_at": null, "created_at": "2026-09-20T09:00:00+02:00" } ] } ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "events": { "type": "array", "items": {} }, "active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "url", "events", "active", "consecutive_failures", "last_success_at", "disabled_at", "created_at" ] } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] }, "post": { "operationId": "v1.webhooks.store", "description": "Subscribe to delivery events. Use `[\"*\"]` to receive everything.\n\nThe response includes a `secret`: shown **once** and never again. Use\nit to verify the `X-RR-Signature` header on every event we send:\n`hmac_sha256(secret, timestamp + \".\" + sha256(raw_body))`.\n\nURLs must use HTTPS and resolve to a public address.", "summary": "Register a webhook endpoint", "tags": [ "Webhooks", "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "examples": [ { "url": "https://example.com/hooks/roadrunner", "events": [ "delivery.dispatched", "delivery.delivered", "delivery.failed" ] } ], "properties": { "url": { "type": "string", "description": "Where we should POST. HTTPS, reachable from the internet, and\nnot an address on a private network: we check before we store\nit and again before every send.", "maxLength": 512 }, "events": { "type": "array", "description": "Which events to send here, at least one. See the Webhooks guide\nfor the full list.", "items": { "type": "string", "description": "An event name, e.g. \"delivery.delivered\".", "maxLength": 64 }, "minItems": 1 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "The endpoint was registered. `secret` is shown ONCE: store it now.\n\n```json\n{\n \"id\": \"whk_01JAV3K2QX8M4N7P\",\n \"object\": \"webhook_endpoint\",\n \"url\": \"https://example.com/hooks/roadrunner\",\n \"events\": [\n \"delivery.dispatched\",\n \"delivery.delivered\",\n \"delivery.failed\"\n ],\n \"active\": true,\n \"consecutive_failures\": 0,\n \"last_success_at\": null,\n \"disabled_at\": null,\n \"created_at\": \"2026-09-21T14:30:00+02:00\",\n \"secret\": \"whsec_EXAMPLESECRETVALUE000000000000000000000\"\n}\n```", "content": { "application/json": { "schema": { "type": "array", "examples": [ { "id": "whk_01JAV3K2QX8M4N7P", "object": "webhook_endpoint", "url": "https://example.com/hooks/roadrunner", "events": [ "delivery.dispatched", "delivery.delivered", "delivery.failed" ], "active": true, "consecutive_failures": 0, "last_success_at": null, "disabled_at": null, "created_at": "2026-09-21T14:30:00+02:00", "secret": "whsec_EXAMPLESECRETVALUE000000000000000000000" } ], "items": {} } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "v1.webhooks.destroy", "description": "Stops all future messages to it immediately. In-flight retries are\nabandoned rather than delivered.", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks", "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "v1.webhooks.test", "description": "Sends a synthetic `delivery.delivered` event to the endpoint, signed\nexactly like a real one, and reports the status code, latency and the\nfirst 256 bytes of the response.\n\nUse this to prove your handler and your signature verification work\nbefore real deliveries depend on them.", "summary": "Test a webhook endpoint", "tags": [ "Webhooks", "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result of calling your endpoint. `delivered` is true only for a 2xx.\n\n```json\n{\n \"delivered\": true,\n \"status_code\": 200,\n \"duration_ms\": 184,\n \"body_preview\": \"ok\",\n \"body_truncated\": false\n}\n```", "content": { "application/json": { "schema": { "examples": [ { "delivered": true, "status_code": 200, "duration_ms": 184, "body_preview": "ok", "body_truncated": false } ], "anyOf": [ { "type": "object", "properties": { "delivered": { "type": "string" }, "status_code": { "type": "string" }, "duration_ms": { "type": "string" }, "body_preview": { "type": "string" }, "body_truncated": { "type": "string" } }, "required": [ "delivered", "status_code", "duration_ms", "body_preview", "body_truncated" ] }, { "type": "object", "properties": { "delivered": { "type": "boolean" }, "error": { "type": "string" }, "duration_ms": { "type": "string" } }, "required": [ "delivered", "error", "duration_ms" ] } ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } }, "/v1/webhooks/{id}/rotate": { "post": { "operationId": "v1.webhooks.rotate", "description": "Issues a new secret and keeps the old one valid for a window.\n\nThe response carries the new secret ONCE. Both secrets sign outgoing\nmessages until the overlap expires, so this can be called before the\nclient has deployed anything.", "summary": "Roll the signing secret", "tags": [ "Webhooks", "Webhook" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "secret": { "type": "string" }, "previous_secret_valid_until": { "type": "string" }, "note": { "type": "string", "const": "Store this secret now: it is not shown again. Messages are signed with both the new and the previous secret until the date above, so deploy whenever suits you. X-RR-Signature may carry several comma-separated signatures; accept the message if any of them matches." } }, "required": [ "id", "object", "url", "secret", "previous_secret_valid_until", "note" ] } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "authentication_error", "code": "invalid_signature", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "not_found", "code": "not_found", "message": "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.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests for this client. Back off and retry; the response carries Retry-After and X-RateLimit-* headers.", "request_id": "req_01JAV3K2QX8M4N7P" } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Broad class of failure, stable across releases." }, "code": { "type": "string", "description": "The specific reason. Switch on this." }, "message": { "type": "string", "description": "Human-readable, safe to log. Not for matching on." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "security": [ { "keyId": [], "timestamp": [], "signature": [] } ] } } }, "components": { "securitySchemes": { "keyId": { "type": "apiKey", "description": "Your key id, as `Bearer rr_live_\u2026`. Sent on every request, including GETs.", "in": "header", "name": "Authorization" }, "timestamp": { "type": "apiKey", "description": "Unix seconds at the moment you sign. Requests more than 300 seconds from our clock are refused with `timestamp_out_of_range`, so sign immediately before sending rather than reusing a value.", "in": "header", "name": "X-RR-Timestamp" }, "signature": { "type": "apiKey", "description": "Lowercase hex HMAC-SHA256 of `key_id.timestamp.METHOD.host+path.sha256(body)`, keyed by your secret. See Authentication in the overview for a worked example and a working shell implementation: the curl samples on this page do NOT include it.", "in": "header", "name": "X-RR-Signature" } }, "schemas": { "CreateDeliveryRequest": { "type": "object", "examples": [ { "client_reference": "ABC-10432", "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", "country": "Zimbabwe", "instructions": "Gate code 4471. Call on arrival." }, "items": [ { "name": "Widget, large", "quantity": 2, "unit_price": 1250, "notes": "Handle with care" } ], "delivery_fee": 500, "tax": 0, "currency": "USD", "payment_type": "prepaid", "metadata": { "order_type": "retail" } } ], "properties": { "quote_id": { "type": [ "string", "null" ], "description": "The id from a POST /v1/quotes response. Supply it to hold the\nprice you were quoted; leave it out and the delivery is priced\nwhen we receive it.", "maxLength": 64 }, "client_reference": { "type": "string", "description": "Your own order number. It must be unique to your account, and it\nis what you will recognise the delivery by in the portal, on the\ntracking page and in support conversations.", "maxLength": 64 }, "pickup_location": { "type": [ "string", "null" ], "description": "A saved pickup location by id (`pl_\u2026`, from GET\n/v1/pickup-locations). Send this or `pickup`, not both; send\nneither and we use your default location.", "maxLength": 40 }, "pickup": { "type": "object", "description": "Where the courier collects. Leave it out and we use the pickup\naddress held on your account.", "properties": { "name": { "type": [ "string", "null" ], "description": "Who to ask for at collection, if not your business name.", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "description": "A number the courier can call if they cannot find the counter.", "maxLength": 32 }, "address": { "type": "string", "description": "Street address including the suburb, e.g. \"10 Example Avenue,\n Msasa, Harare\". Required once you send a pickup object at all.", "maxLength": 512 }, "instructions": { "type": [ "string", "null" ], "description": "Anything the courier needs to know to collect: which door, which\ncounter, who to ask for.", "maxLength": 1000 } } }, "dropoff": { "type": "object", "description": "Where the parcel is going, and who is waiting for it.", "properties": { "name": { "type": "string", "description": "The recipient's name as they gave it to you. One field, not two:\nthe tracking page shows only the first word of it.", "maxLength": 255 }, "phone": { "type": "string", "description": "A Zimbabwean mobile number the courier can call on arrival.\nAccepted as 07\u2026, 2637\u2026 or +2637\u2026.", "maxLength": 32 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Optional. Only used if we ever need to reach the recipient in\nwriting; it never appears on the public tracking page.", "maxLength": 255 }, "address": { "type": "string", "description": "Street address including the suburb. The suburb is what the\nrecipient sees on the tracking page and what the price is\nmeasured against, so a vague address costs you accuracy.", "maxLength": 512 }, "country": { "type": [ "string", "null" ], "description": "Defaults to Zimbabwe. We deliver inside Zimbabwe only, so an\naddress anywhere else is refused before a courier is sent.", "maxLength": 64 }, "instructions": { "type": [ "string", "null" ], "description": "Gate codes, floor numbers, \"call on arrival\": whatever the\ncourier needs to complete the drop without phoning you.", "maxLength": 1000 } }, "required": [ "name", "phone", "address" ] }, "items": { "type": "array", "description": "What is in the parcel. At least one item, at most 100.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What the item is, in words a courier would understand.", "maxLength": 255 }, "quantity": { "type": "integer", "description": "How many of this item. Whole numbers, at least 1.", "minimum": 1 }, "unit_price": { "type": "integer", "description": "Price for ONE of this item, in cents. 1250 is $12.50.", "minimum": 0 }, "notes": { "type": [ "string", "null" ], "description": "Handling notes for this item: fragile, cold chain, upright.", "maxLength": 500 } }, "required": [ "name", "quantity", "unit_price" ] }, "minItems": 1, "maxItems": 100 }, "delivery_fee": { "type": [ "integer", "null" ], "description": "What you are charging your customer for delivery, in cents.\nThis is your figure, not ours; it does not change what we bill\nyou. Leave it out and we price the delivery ourselves.", "minimum": 0 }, "tax": { "type": [ "integer", "null" ], "description": "Tax on the order, in cents, if you itemise it.", "minimum": 0 }, "currency": { "type": [ "string", "null" ], "description": "Three-letter code, e.g. \"USD\". Defaults to USD.", "minLength": 3, "maxLength": 3 }, "payment_type": { "type": [ "string", "null" ], "description": "\"prepaid\" if the customer has already paid you, or\n\"cash_on_delivery\" if the courier must collect money. Defaults\nto prepaid.", "enum": [ "prepaid", "cash_on_delivery", null ] }, "service_level": { "type": [ "string", "null" ], "description": "How fast you need it: `standard`, `express` or `scheduled`.\nExpress costs more and scheduled can cost less; what your\naccount pays for each is on your profile page. Defaults to\nstandard, which is what every delivery booked before this\nexisted was.", "enum": [ "standard", "express", "scheduled", null ] }, "cash_to_collect": { "type": [ "integer", "null" ], "description": "How much the courier must collect, in cents. Required when\npayment_type is cash_on_delivery, and refused otherwise.", "minimum": 1 }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time", "description": "Book a collection for later instead of now. ISO 8601, read as\nUTC, at least a minute ahead and at most seven days out." }, "metadata": { "type": [ "array", "null" ], "description": "Up to 20 key/value pairs of your own. We store them and hand\nthem back on every read; we never act on them.", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "client_reference", "dropoff", "items" ], "title": "CreateDeliveryRequest" }, "DeliveryResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "delivery" }, "client_reference": { "type": "string" }, "status": { "type": "string" }, "test_mode": { "type": "boolean" }, "pickup": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ], "description": "The saved location it came from (pl_\u2026), or null when the\npickup was given with the booking." } }, "required": [ "name", "phone", "address", "instructions", "location" ] }, "dropoff": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] } }, "required": [ "name", "phone", "email", "address", "instructions" ] }, "items": { "type": "array", "items": {} }, "payment_type": { "type": "string" }, "service_level": { "$ref": "#/components/schemas/ServiceLevel" }, "cash_to_collect": { "type": [ "object", "null" ], "properties": { "amount": { "type": [ "integer", "null" ] }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "pricing": { "type": "object", "properties": { "subtotal": { "type": [ "object", "null" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "delivery_fee": { "type": [ "object", "null" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tax": { "type": [ "object", "null" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "total": { "type": [ "object", "null" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "subtotal", "delivery_fee", "tax", "total" ] }, "scheduled_for": { "type": [ "string", "null" ] }, "hold": { "type": [ "object", "null" ], "description": "Outside the area we cover: the booking stands, but no courier\nis sent until Road Runner has spoken to you. Null otherwise.", "properties": { "reasons": { "type": "array", "items": { "type": "string" } }, "message": { "type": [ "string", "null" ] }, "since": { "type": [ "string", "null" ] } }, "required": [ "reasons", "message", "since" ] }, "tracking_url": { "type": "string" }, "courier": { "type": [ "object", "null" ], "description": "Who is carrying it, once a courier has accepted it. Null before\nthat, and again if the courier is taken off the job.", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "phone" ] }, "eta": { "type": [ "string", "null" ], "description": "When it is expected to arrive, while it is on its way. Null once\nit has finished, or when the courier network has no estimate." }, "proof_of_delivery": { "type": [ "object", "null" ], "description": "Photos the courier took at the door, when they took any. Links\nare hosted by the courier network.", "properties": { "photo_urls": { "type": "array", "items": {} } }, "required": [ "photo_urls" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "dispatched_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_reason": { "type": [ "string", "null" ], "description": "Why, when cancelled: customer_cancelled, merchant_cancelled,\nduplicate, address_problem, other, or hold_expired (held for\nRoad Runner and not decided in time; not charged)." }, "provider_state": { "type": [ "string", "null" ], "description": "Never expose which provider, or its ids (D1)." } }, "required": [ "id", "object", "client_reference", "status", "test_mode", "pickup", "dropoff", "items", "payment_type", "service_level", "cash_to_collect", "pricing", "scheduled_for", "hold", "tracking_url", "courier", "eta", "proof_of_delivery", "created_at", "updated_at", "dispatched_at", "delivered_at", "cancelled_at", "cancellation_reason" ], "title": "DeliveryResource" }, "ServiceLevel": { "type": "string", "description": "How fast the client is asking us to move. Road Runner sold one speed, which meant a pharmacy needing insulin in the next hour and a bookshop happy with \"sometime today\" paid the same and got the same. Speed is the thing couriers charge for everywhere, and it was the one lever missing from pricing. Each level is a percentage of the base fee rather than a fixed surcharge, because express on a 28 km run costs us far more than express on a 4 km run, and a flat surcharge would undercharge exactly the jobs that hurt.\n| |\n|---|\n| `standard`
Same working day, our normal promise. |\n| `express`
Straight there, ahead of the queue. |\n| `scheduled`
Booked for a time we choose the route around, so it costs us less. |", "enum": [ "standard", "express", "scheduled" ], "title": "ServiceLevel" }, "UpdateDeliveryRequest": { "type": "object", "examples": [ { "dropoff": { "instructions": "Leave with the security desk at reception" } } ], "properties": { "dropoff": { "type": "object", "description": "Correcting where it is going. Send only the parts that change.", "properties": { "name": { "type": "string", "description": "The recipient's name, if you had it wrong.", "maxLength": 255 }, "phone": { "type": "string", "description": "A different number to reach them on.", "maxLength": 32 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "A different email address, or null to remove the one on file.", "maxLength": 255 }, "address": { "type": "string", "description": "A corrected address. Changing it after a courier is on the way\nmay change what the delivery costs.", "maxLength": 512 }, "instructions": { "type": [ "string", "null" ], "description": "New or amended instructions for the courier.", "maxLength": 1000 } } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time", "description": "Same bound as create. Without it a client could not schedule\n30 days out on POST but could on PATCH, which is the kind of\ndifference nobody discovers until it is in production. Move the collection to a different time. ISO 8601, read as UTC,\nat least a minute ahead and at most seven days out." }, "metadata": { "type": [ "array", "null" ], "description": "Replaces the stored metadata outright rather than merging into\nit. Up to 20 key/value pairs.", "items": { "type": "string" }, "maxItems": 20 } }, "title": "UpdateDeliveryRequest" } }, "responses": { "ValidationException": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "validation_error", "code": "validation_failed", "message": "The request was understood but its contents were rejected.", "request_id": "req_01JAV3K2QX8M4N7P", "details": [ { "field": "dropoff.phone", "issue": "The dropoff.phone field is required." } ] } } ], "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Always `validation_error` here." }, "code": { "type": "string", "description": "Machine-readable reason, e.g. `validation_failed`." }, "message": { "type": "string", "description": "Human-readable. Do not match on it." }, "request_id": { "type": "string", "description": "Quote this when asking us about a request." }, "details": { "type": "array", "description": "Present when individual fields are at fault; absent for whole-request refusals.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Dotted path to the field at fault, e.g. `dropoff.phone`." }, "issue": { "type": "string", "description": "Why that field was rejected." } }, "required": [ "field", "issue" ] } } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }