{ "openapi": "3.1.0", "info": { "title": "Delivahere Partner API", "version": "1.0.0", "summary": "Book, pay for and track Delivahere deliveries for your own customers.", "description": "Create deliveries for your customers, pay for them, hand over codes and follow every delivery by webhook. JSON over HTTPS; authenticate every request with the `client_id` and `secret_key` headers Delivahere issues to you.", "contact": { "name": "Delivahere partner support", "email": "dev@delivahere.com" }, "license": { "name": "Proprietary. For Delivahere partners only." } }, "servers": [ { "url": "http://103.187.101.50:8721/request/public", "description": "QA", "x-environment": "qa" }, { "url": "https://admin.delivahere.com/request/public", "description": "Live", "x-environment": "live" } ], "security": [ { "clientId": [], "secretKey": [] } ], "tags": [ { "name": "Users and sessions", "description": "Find senders and open per-user sessions." }, { "name": "Deliveries", "description": "Create, read and cancel deliveries." }, { "name": "Bids and payment", "description": "See delivery partner agent bids, accept one, check the wallet." }, { "name": "Pricing", "description": "Suggest an offer before creating a delivery. Advisory only; nothing is saved." }, { "name": "Media", "description": "Upload package photos." }, { "name": "Tracking", "description": "Public, redacted tracking for links you share." }, { "name": "Delivery lifecycle", "description": "Webhook events: delivery lifecycle.", "x-webhook": true }, { "name": "Bids", "description": "Webhook events: bids.", "x-webhook": true }, { "name": "Pickup and drop-off", "description": "Webhook events: pickup and drop-off.", "x-webhook": true }, { "name": "Exceptions", "description": "Webhook events: exceptions.", "x-webhook": true }, { "name": "Payments", "description": "Webhook events: payments.", "x-webhook": true }, { "name": "Accounts", "description": "Webhook events: accounts.", "x-webhook": true } ], "x-tagGroups": [ { "name": "Endpoints", "tags": [ "Users and sessions", "Deliveries", "Bids and payment", "Pricing", "Media", "Tracking" ] }, { "name": "Webhooks", "tags": [ "Delivery lifecycle", "Bids", "Pickup and drop-off", "Exceptions", "Payments", "Accounts" ] } ], "paths": { "/users/lookup": { "post": { "tags": [ "Users and sessions" ], "operationId": "lookupUser", "summary": "Check whether a sender exists", "description": "Never creates an account. Users you can't act for (not created through your channel and not linked to you) are reported as `exists: false`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Phone number. Send it with the country code and no `+` (`2348012345678`), or send the national number with `countryCode`.", "examples": [ "2348012345678" ] }, "countryCode": { "type": "string", "description": "Country calling code, when `mobile` is a national number.", "examples": [ "234" ] } } }, "example": { "mobile": "2348012345678" } } } }, "responses": { "200": { "description": "Lookup result.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "object", "required": [ "exists" ], "properties": { "exists": { "type": "boolean", "description": "Whether the sender exists and is yours to act for." }, "userId": { "type": "integer", "description": "When `exists`." }, "name": { "type": [ "string", "null" ], "description": "When `exists`." }, "mobile": { "type": [ "string", "null" ], "description": "When `exists`: E.164 without `+`." }, "email": { "type": [ "string", "null" ], "description": "When `exists`.", "x-sensitive": true }, "userReferralCode": { "type": [ "string", "null" ], "description": "When `exists`." } } } } } ] }, "example": { "responseMessage": "Account found", "status": 200, "resourceData": { "exists": true, "userId": 4567, "name": "Ada Obi", "userReferralCode": "ADA123", "mobile": "2348012345678", "email": "ada@example.com" } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/session": { "post": { "tags": [ "Users and sessions" ], "operationId": "createSession", "summary": "Open a session for a sender", "description": "Returns a `sessionToken` for user-scoped calls (`X-Session-Token`). Valid for 24 hours and only with your `client_id`. Open a new one when it expires; there's no refresh. Treat it like a password.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Phone number. Send it with the country code and no `+` (`2348012345678`), or send the national number with `countryCode`.", "examples": [ "2348012345678" ] }, "countryCode": { "type": "string", "description": "Country calling code, when `mobile` is a national number.", "examples": [ "234" ] } } }, "example": { "mobile": "2348012345678" } } } }, "responses": { "200": { "description": "Session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "object", "required": [ "sessionToken", "userId", "expiresAt" ], "properties": { "sessionToken": { "type": "string", "description": "Send as `X-Session-Token`.", "pattern": "^ses_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "userId": { "type": "integer", "description": "Sender's user ID." }, "name": { "type": [ "string", "null" ], "description": "Sender's name." }, "expiresAt": { "type": "string", "description": "Expiry (24 hours).", "format": "date-time" } } } } } ] }, "example": { "responseMessage": "Session created", "status": 200, "resourceData": { "sessionToken": "ses_Hk3pQ9zR2vW8yLm4Xc7Tb1Nd6Fg0Js5Ae2Ku9Io3Py8", "userId": 4567, "name": "Ada Obi", "expiresAt": "2026-11-04T10:15:30.000+0000" } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/media": { "post": { "tags": [ "Media" ], "operationId": "uploadMedia", "summary": "Upload a package photo", "description": "Upload a photo, then pass its `url` in `mediaUrls` when creating the delivery. Keep files under 1 MB (JPEG, PNG or WebP).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The image." }, "purpose": { "type": "string", "default": "packagePhoto", "description": "Leave as `packagePhoto`." } } } } } }, "responses": { "200": { "description": "Uploaded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "object", "properties": { "mediaId": { "type": "integer", "description": "Media ID." }, "url": { "type": "string", "description": "Pass this in `mediaUrls`.", "format": "uri" }, "purpose": { "type": "string", "description": "Purpose." }, "contentType": { "type": "string", "description": "MIME type." }, "size": { "type": "integer", "description": "Bytes." } } } } } ] }, "example": { "responseMessage": "Media uploaded", "status": 200, "resourceData": { "mediaId": 8812, "url": "https://prod-deliva.s3.amazonaws.com/images/public-media/6f1c0e.jpg", "purpose": "packagePhoto", "contentType": "image/jpeg", "size": 81234 } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/createRequestWithUser": { "post": { "tags": [ "Deliveries" ], "operationId": "createDelivery", "summary": "Create a delivery", "description": "Creates the delivery and opens it to delivery partner agents straight away. If `mobile` isn't a Delivahere customer yet, send `fullName` and `email` to register them (otherwise `422`). Send an `Idempotency-Key` so a retry never books twice.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended. A unique key per action (e.g. your order ID plus the action). A retry with the same key and body replays the first response for 24 hours. Keys are shared across endpoints for your client, so never reuse one for a different action.", "schema": { "type": "string", "maxLength": 255, "examples": [ "order-5521-create" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeliveryRequest" }, "example": { "mobile": "2348012345678", "fullName": "Ada Obi", "email": "ada@example.com", "title": "Order #5521", "weightClass": "light", "vehicleType": "MOTORCYCLE", "declaredValueAmount": 50000, "offerAmount": 5000, "currency": "NGN", "sourceStreetAddress": "12 Marina Rd", "sourceCity": "Lagos", "sourceState": "Lagos", "sourceCountry": "NG", "sourceLatitude": 6.45, "sourceLongitude": 3.39, "pickupName": "Acme Warehouse", "pickupMobile": "2348011111111", "destinationStreetAddress": "5 Ring Rd", "destinationCity": "Ibadan", "destinationState": "Oyo", "destinationCountry": "NG", "destinationLatitude": 7.38, "destinationLongitude": 3.94, "receiverName": "Bola A.", "receiverMobile": "2348098765432", "autoVerifyPickup": true, "autoBidAccept": true, "maxBidAmount": 4500, "notifySender": false, "sendDropOffCode": false } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "$ref": "#/components/schemas/CreateDeliveryResult" } } } ] }, "example": { "responseMessage": "Local Delivery Request Success", "status": 200, "resourceData": { "requestId": 123, "deliveryId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "status": "PENDING", "currency": "NGN", "userId": 4567, "delivaPkgProtectedInsurance": false } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "402": { "description": "The wallet couldn't pay. `error.code` is the reason: `INSUFFICIENT_WALLET_BALANCE`, `NO_WALLET`, `AUTO_BID_HOLD_USED`, `WALLET_LIMIT_EXCEEDED`, or `PAYMENT_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_WALLET_BALANCE", "message": "INSUFFICIENT_WALLET_BALANCE" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "409": { "description": "`IDEMPOTENCY_IN_PROGRESS` (retry shortly), `IDEMPOTENCY_CONFLICT` (key reused with a different body) or `DELIVERY_NOT_CANCELLABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency-Key 'order-5521' was already used with a different request body" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "422": { "description": "New sender: send the fields listed in `error.requiredFields` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "USER_REGISTRATION_REQUIRED", "message": "No user found for this mobile. Provide fullName and email to register.", "requiredFields": [ "fullName", "email" ] }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries": { "get": { "tags": [ "Deliveries" ], "operationId": "listDeliveries", "summary": "List a sender's deliveries", "description": "The session user's deliveries created through your channel, newest first.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter on the list's `status` (internal values, e.g. `PUBLISHED`, `IN_TRANSIT`, `DELIVERED`).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Zero-based page.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "size", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "A page of deliveries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryListItem" } } } } } } ] }, "example": { "responseMessage": "Success", "status": 200, "resourceData": { "items": [ { "customerId": 4567, "requestId": 123, "title": "Order #5521", "status": "PUBLISHED", "requestType": "INTERSTATE", "sourceCity": "Lagos", "destinationCity": "Ibadan", "favourited": false, "bundle": false } ] }, "totalRecords": 1, "noOfRecords": 1 } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries/{idOrCode}": { "get": { "tags": [ "Deliveries" ], "operationId": "getDelivery", "summary": "Get a delivery", "description": "Full detail, including codes and contacts, for the delivery's sender. Only deliveries created through your channel.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "idOrCode", "in": "path", "required": true, "description": "Delivery ID (`123`) or tracking code (`DLV-000123`). Not the `trackingToken`.", "schema": { "type": "string", "pattern": "^([Dd][Ll][Vv]-)?\\d+$", "examples": [ "DLV-000123" ] } } ], "responses": { "200": { "description": "The delivery.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "$ref": "#/components/schemas/DeliveryDetail" } } } ] }, "example": { "responseMessage": "SUCCESS", "status": 200, "resourceData": { "requestId": 123, "customerId": 4567, "title": "Order #5521", "publicStatus": "ACCEPTED", "status": "ACCEPTED_BID", "currency": "NGN", "value": 50000, "bidAmount": 5000, "acceptedBidAmount": 4200, "weightClass": "light", "vehicleType": "MOTORCYCLE", "sourceCity": "Lagos", "destinationCity": "Ibadan", "senderName": "Ada Obi", "receiverName": "Bola A.", "receiverMobile": "+2348098765432", "partnerName": "Emeka O.", "partnerContact": "+2348033333333", "dropOffCode": "4821", "isBundle": false } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries/{idOrCode}/timeline": { "get": { "tags": [ "Deliveries" ], "operationId": "getTimeline", "summary": "Get a delivery's transit legs", "description": "When the package reached each leg. For a full, ordered history use `GET /track/{trackingToken}`.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "idOrCode", "in": "path", "required": true, "description": "Delivery ID (`123`) or tracking code (`DLV-000123`). Not the `trackingToken`.", "schema": { "type": "string", "pattern": "^([Dd][Ll][Vv]-)?\\d+$", "examples": [ "DLV-000123" ] } } ], "responses": { "200": { "description": "Transit legs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "$ref": "#/components/schemas/Timeline" } } } ] }, "example": { "responseMessage": "success", "status": 200, "resourceData": { "requestId": 123, "title": "Order #5521", "requestType": "INTERSTATE", "expectedDeliveryDate": "2026-11-04T16:00:00.000+0000", "docketNumber": "0", "opcDetail": null, "daDetail": { "transitDate": "2026-11-03T11:02:00.000+0000", "mediaUrls": [] }, "dpcDetail": null, "rcDetail": null } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries/{idOrCode}/cancel": { "post": { "tags": [ "Deliveries" ], "operationId": "cancelDelivery", "summary": "Cancel a delivery", "description": "Allowed until the delivery partner agent collects the package. After acceptance the payment is refunded to the source that paid (gateway fees on card and link payments aren't refundable). After pickup: `409 DELIVERY_NOT_CANCELLABLE`. Use a fresh `Idempotency-Key` per delivery.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "idOrCode", "in": "path", "required": true, "description": "Delivery ID (`123`) or tracking code (`DLV-000123`). Not the `trackingToken`.", "schema": { "type": "string", "pattern": "^([Dd][Ll][Vv]-)?\\d+$", "examples": [ "DLV-000123" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended. A unique key per action (e.g. your order ID plus the action). A retry with the same key and body replays the first response for 24 hours. Keys are shared across endpoints for your client, so never reuse one for a different action.", "schema": { "type": "string", "maxLength": 255, "examples": [ "order-5521-create" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why you're cancelling." } } }, "example": { "reason": "Customer cancelled the order" } } } }, "responses": { "200": { "description": "Cancelled. `resourceData` is the delivery ID. Check the body `status`: in a rare race it is 400 with HTTP 200, meaning not cancelled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "integer", "description": "Delivery ID." } } } ] }, "example": { "responseMessage": "Cancelled Request Successfully", "status": 200, "resourceData": 123 } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "409": { "description": "`IDEMPOTENCY_IN_PROGRESS` (retry shortly), `IDEMPOTENCY_CONFLICT` (key reused with a different body) or `DELIVERY_NOT_CANCELLABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency-Key 'order-5521' was already used with a different request body" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries/{idOrCode}/bids": { "get": { "tags": [ "Bids and payment" ], "operationId": "listBids", "summary": "List bids on a delivery", "description": "Open bids from delivery partner agents. `totalAmountToBePaid` is what accepting the bid costs.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "idOrCode", "in": "path", "required": true, "description": "Delivery ID (`123`) or tracking code (`DLV-000123`). Not the `trackingToken`.", "schema": { "type": "string", "pattern": "^([Dd][Ll][Vv]-)?\\d+$", "examples": [ "DLV-000123" ] } } ], "responses": { "200": { "description": "Bids.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "array", "items": { "$ref": "#/components/schemas/Bid" } } } } ] }, "example": { "responseMessage": "Success", "status": 200, "resourceData": [ { "bidId": 9876, "daId": 3321, "name": "Emeka O.", "rating": 4.6, "bidAmount": 4200, "currency": "NGN", "comment": "Can pick up in 20 minutes", "totalAmountToBePaid": "4620", "platformFee": 420, "insuranceAmount": 0, "vehicleType": "MOTORCYCLE" } ] } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/deliveries/{idOrCode}/bids/{bidId}/accept": { "post": { "tags": [ "Bids and payment" ], "operationId": "acceptBid", "summary": "Accept a bid", "description": "Accepts and pays for a bid. `paymentMethod`:\n\n- `AUTO` (recommended): wallet, then saved card, then a payment link.\n- `WALLET`: wallet only; `402` if it can't pay.\n- `CARD`: saved card; falls back to a payment link if the card fails.\n- `LINK` (default when omitted): a payment link; the bid is accepted once it's paid.\n\nThe result is one of three shapes; check `resourceData.status` (`ACCEPTED`, `PAYMENT_PENDING`) or `paymentUrl` (link).", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "idOrCode", "in": "path", "required": true, "description": "Delivery ID (`123`) or tracking code (`DLV-000123`). Not the `trackingToken`.", "schema": { "type": "string", "pattern": "^([Dd][Ll][Vv]-)?\\d+$", "examples": [ "DLV-000123" ] } }, { "name": "bidId", "in": "path", "required": true, "description": "Bid ID.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended. A unique key per action (e.g. your order ID plus the action). A retry with the same key and body replays the first response for 24 hours. Keys are shared across endpoints for your client, so never reuse one for a different action.", "schema": { "type": "string", "maxLength": 255, "examples": [ "order-5521-create" ] } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "AUTO", "WALLET", "CARD", "LINK" ], "default": "LINK" } } }, "example": { "paymentMethod": "AUTO" } } } }, "responses": { "200": { "description": "Accepted and paid, card payment processing (body `status: 202`), or a payment link to pay.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "oneOf": [ { "title": "Accepted", "type": "object", "required": [ "bidId", "status", "method" ], "properties": { "bidId": { "type": "integer", "description": "Bid ID." }, "status": { "const": "ACCEPTED" }, "method": { "type": "string", "enum": [ "WALLET", "CARD" ] } } }, { "title": "Payment pending", "type": "object", "required": [ "bidId", "status" ], "properties": { "bidId": { "type": "integer", "description": "Bid ID." }, "status": { "const": "PAYMENT_PENDING" }, "method": { "const": "CARD" } } }, { "title": "Payment link", "type": "object", "description": "The bid waits for this payment link. It is accepted once paid (`delivery.bid_accepted`).", "required": [ "bidId", "paymentUrl" ], "properties": { "bidId": { "type": "integer", "description": "Bid ID." }, "paymentUrl": { "type": "string", "description": "Hosted payment page. Send it to whoever pays.", "format": "uri" }, "reference": { "type": "string", "description": "Payment reference." }, "amount": { "type": "number", "description": "Amount due, in major units." }, "currency": { "type": "string", "description": "ISO currency code." }, "expiresAt": { "type": "string", "description": "The link expires after one hour.", "format": "date-time" }, "method": { "type": "string", "description": "`LINK` when `AUTO` or `CARD` fell back to a link.", "const": "LINK" }, "fallbackReason": { "type": [ "string", "null" ], "description": "Why it fell back: `NO_WALLET`, `INSUFFICIENT_WALLET_BALANCE`, `NO_SAVED_CARD` or `CARD_DECLINED`." } } } ] } } } ] }, "examples": { "accepted": { "summary": "Paid from the wallet", "value": { "responseMessage": "Bid accepted and paid.", "status": 200, "resourceData": { "bidId": 9876, "status": "ACCEPTED", "method": "WALLET" } } }, "link": { "summary": "Fell back to a payment link", "value": { "responseMessage": "Payment link created. Confirming payment within 1 hour accepts this bid.", "status": 200, "resourceData": { "bidId": 9876, "paymentUrl": "https://checkout.paystack.com/abc123", "reference": "DLV_123_9876", "amount": 4620, "currency": "NGN", "expiresAt": "2026-11-03T11:30:00.000+0000", "method": "LINK", "fallbackReason": "INSUFFICIENT_WALLET_BALANCE" } } }, "pending": { "summary": "Card payment processing", "value": { "responseMessage": "Card payment is processing; the bid is accepted once it completes.", "status": 202, "resourceData": { "bidId": 9876, "status": "PAYMENT_PENDING", "method": "CARD" } } } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "402": { "description": "The wallet couldn't pay. `error.code` is the reason: `INSUFFICIENT_WALLET_BALANCE`, `NO_WALLET`, `AUTO_BID_HOLD_USED`, `WALLET_LIMIT_EXCEEDED`, or `PAYMENT_FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_WALLET_BALANCE", "message": "INSUFFICIENT_WALLET_BALANCE" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "404": { "description": "Not found, or not yours. Deliveries and users you can't act for look exactly like ones that don't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Delivery not found" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "409": { "description": "`IDEMPOTENCY_IN_PROGRESS` (retry shortly), `IDEMPOTENCY_CONFLICT` (key reused with a different body) or `DELIVERY_NOT_CANCELLABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency-Key 'order-5521' was already used with a different request body" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/wallet/balance": { "get": { "tags": [ "Bids and payment" ], "operationId": "getWalletBalance", "summary": "Get the sender's wallet balance", "description": "Prepaid balance used by `AUTO` and `WALLET` payments. Fund it by bank transfer; Delivahere credits it.", "security": [ { "clientId": [], "secretKey": [], "sessionToken": [] } ], "parameters": [ { "name": "currency", "in": "query", "required": false, "description": "Wallet currency (default: the most recently used wallet).", "schema": { "type": "string", "examples": [ "NGN" ] } } ], "responses": { "200": { "description": "Balance, in major units.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "type": "object", "properties": { "balance": { "type": "number", "description": "Spendable balance." }, "availableBalance": { "type": "number", "description": "Same as `balance`." }, "reservedBalance": { "type": "number", "description": "Held for auto-accept jobs." }, "totalBalance": { "type": "number", "description": "Available plus reserved." }, "maxBalance": { "type": "number", "description": "Wallet cap." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency (null when there's no wallet yet)." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last change." } } } } } ] }, "example": { "responseMessage": "Wallet balance retrieved", "status": 200, "resourceData": { "balance": 25000, "availableBalance": 25000, "reservedBalance": 4500, "totalBalance": 29500, "maxBalance": 5000000, "currency": "NGN", "updatedAt": "2026-11-03T09:00:00.000+0000" } } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/pricing/recommend": { "post": { "tags": [ "Pricing" ], "operationId": "recommendPrice", "summary": "Recommend an offer", "description": "A quick low / optimal / high range for `offerAmount`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "pickup", "dropoff" ], "properties": { "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "pickup": { "$ref": "#/components/schemas/GeoPoint" }, "dropoff": { "$ref": "#/components/schemas/GeoPoint" }, "weightClass": { "type": "string", "description": "`light`, `medium`, `heavy`, `extra_heavy` (or `SMALL`, `MEDIUM`, `LARGE`, `EXTRA_LARGE`, `FREIGHT`)." }, "weight": { "type": "number", "description": "Weight, instead of `weightClass`.", "minimum": 0 }, "weightUnit": { "type": "string", "enum": [ "KG", "LBS" ] }, "vehicleType": { "type": "string", "enum": [ "MOTORCYCLE", "BICYCLE", "TRICYCLE", "SEDAN", "SUV", "MINIVAN", "PANEL_VAN", "PICKUP_TRUCK", "MINI_TRUCK_6T", "LIGHT_TRUCK_OPEN", "LIGHT_TRUCK_CONTAINER", "MEDIUM_TRUCK_10T", "MEDIUM_TRUCK_12T", "HEAVY_TRUCK_16T", "HEAVY_TRUCK_18T_CONTAINER", "HEAVY_TRUCK_25T", "EXTRA_HEAVY_30T", "EXTRA_HEAVY_35T", "TRAILER_20FT", "TRAILER_40FT", "NONE_OR_ANY_VEHICLE" ] }, "declaredValue": { "type": "number", "description": "Declared value.", "minimum": 0 }, "distance": { "type": "number", "description": "Known distance, instead of coordinates.", "minimum": 0 }, "distanceUnit": { "type": "string", "enum": [ "Km", "Mi" ] } } }, "example": { "currency": "NGN", "pickup": { "latitude": 6.5244, "longitude": 3.3792 }, "dropoff": { "latitude": 6.4531, "longitude": 3.3958 }, "weightClass": "light", "vehicleType": "MOTORCYCLE", "declaredValue": 15000 } } } }, "responses": { "200": { "description": "Price range.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "$ref": "#/components/schemas/PriceRange" } } } ] }, "example": { "responseMessage": "Recommended price fetched successfully", "status": 200, "resourceData": { "low": 1280, "optimal": 1600, "high": 2400, "currency": "NGN", "distance": { "value": 8.2, "unit": "Km" } } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/pricing/estimate": { "post": { "tags": [ "Pricing" ], "operationId": "estimatePrice", "summary": "Estimate a price with a breakdown", "description": "The same range as `/pricing/recommend`, plus the cost breakdown and which vehicles fit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "pickup", "dropoff" ], "properties": { "currency": { "type": "string", "enum": [ "NGN", "USD" ] }, "pickup": { "$ref": "#/components/schemas/GeoPoint" }, "dropoff": { "$ref": "#/components/schemas/GeoPoint" }, "weight": { "type": "number", "description": "Weight.", "minimum": 0 }, "weightUnit": { "type": "string", "enum": [ "KG", "LBS" ] }, "weightClass": { "type": "string", "description": "Instead of `weight`: `light`, `medium`, `heavy`, `extra_heavy`." }, "dimensions": { "type": "object", "description": "Volumetric weight (L×W×H / 5000, in cm → kg) is used when larger than `weight`.", "properties": { "length": { "type": "number", "description": "" }, "width": { "type": "number", "description": "" }, "height": { "type": "number", "description": "" }, "unit": { "type": "string", "description": "`cm` or `in`." } } }, "declaredValue": { "type": "number", "description": "Declared value.", "minimum": 0 }, "vehicleType": { "type": "string", "enum": [ "MOTORCYCLE", "BICYCLE", "TRICYCLE", "SEDAN", "SUV", "MINIVAN", "PANEL_VAN", "PICKUP_TRUCK", "MINI_TRUCK_6T", "LIGHT_TRUCK_OPEN", "LIGHT_TRUCK_CONTAINER", "MEDIUM_TRUCK_10T", "MEDIUM_TRUCK_12T", "HEAVY_TRUCK_16T", "HEAVY_TRUCK_18T_CONTAINER", "HEAVY_TRUCK_25T", "EXTRA_HEAVY_30T", "EXTRA_HEAVY_35T", "TRAILER_20FT", "TRAILER_40FT", "NONE_OR_ANY_VEHICLE" ], "description": "Leave out to let Delivahere pick a vehicle." }, "scheduledPickupTime": { "type": "string", "description": "Pickup time, if not now.", "format": "date-time" }, "originCity": { "type": "string", "description": "Pickup city (sharpens interstate pricing)." }, "originState": { "type": "string", "description": "Pickup state." }, "destCity": { "type": "string", "description": "Drop-off city." }, "destState": { "type": "string", "description": "Drop-off state." }, "country": { "type": "string", "description": "ISO country code." }, "distance": { "type": "number", "description": "Known distance, instead of coordinates.", "minimum": 0 }, "distanceUnit": { "type": "string", "enum": [ "Km", "Mi" ] } } }, "example": { "currency": "NGN", "pickup": { "latitude": 6.5244, "longitude": 3.3792 }, "dropoff": { "latitude": 7.3775, "longitude": 3.947 }, "weight": 2.5, "weightUnit": "KG", "declaredValue": 15000, "originCity": "Lagos", "originState": "Lagos", "destCity": "Ibadan", "destState": "Oyo", "country": "NG" } } } }, "responses": { "200": { "description": "Estimate.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "resourceData": { "$ref": "#/components/schemas/PriceEstimate" } } } ] }, "example": { "responseMessage": "Price estimate generated successfully", "status": 200, "resourceData": { "low": 5600, "optimal": 7000, "high": 10500, "currency": "NGN", "confidence": "HIGH", "configScope": "CITY_PAIR", "distance": { "value": 128.4, "unit": "Km", "timeMinutes": 140, "source": "HAVERSINE" }, "vehicleType": "MOTORCYCLE", "vehicleInferred": true, "cost": { "baseFare": 500, "distanceCost": 5650, "weightCost": 125, "subtotal": 6275, "factorsMultiplier": 1.1, "pcCharge": 0, "total": 7000 }, "estimationId": "EST-9F3KX7QZ", "expiresAt": "2026-11-03T10:25:30Z" } } } } }, "400": { "description": "Missing or invalid input. `error.message` says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "weightClass is mandatory" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "401": { "description": "Missing or wrong `client_id` / `secret_key`, a deactivated client, or a missing, expired or foreign `X-Session-Token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid client credentials" }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } }, "/track/{trackingToken}": { "get": { "tags": [ "Tracking" ], "operationId": "trackDelivery", "summary": "Public tracking", "description": "Needs no credentials and is redacted (first name and initial, city-level places, masked delivery partner agent phone), so it's safe behind a link you send customers. Always use the `trackingToken`: `DLV-` codes are guessable and may stop working here. This endpoint answers `{success, data}` instead of the usual envelope.", "security": [ {} ], "parameters": [ { "name": "trackingToken", "in": "path", "required": true, "description": "The delivery's `trackingToken`.", "schema": { "type": "string", "examples": [ "q3Zr8Kd0aP1xYt7bWm2cLs4e" ] } } ], "responses": { "200": { "description": "Tracking view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/PublicTracking" } } }, "example": { "success": true, "data": { "trackingCode": "DLV-000123", "status": "IN_TRANSIT", "title": "Order #5521", "senderName": "Ada O.", "receiverName": "Bola A.", "sourceLocation": "Lagos, Lagos", "destinationLocation": "Ibadan, Oyo", "createdAt": "2026-11-03T10:15:30.000+0000", "partner": { "name": "Emeka Okafor", "contact": "+234 *** *** 3333", "vehicleType": "MOTORCYCLE", "latitude": 6.5012, "longitude": 3.3654, "estimatedArrivalMinutes": 18, "etaConfidence": "medium" }, "timeline": [ { "status": "PENDING", "timestamp": "2026-11-03T10:15:30.000+0000", "message": "Delivery request created", "location": { "locationType": "sender", "locationLabel": "Lagos, Lagos", "latitude": 6.45, "longitude": 3.39 } }, { "status": "ACCEPTED", "timestamp": "2026-11-03T10:31:02.000+0000", "message": "Emeka Okafor accepted the delivery", "location": { "locationType": "partner", "locationLabel": "Emeka Okafor", "latitude": 6.47, "longitude": 3.38 } } ], "notices": [] } } } } }, "404": { "description": "No delivery for this reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "TRACKING_NOT_FOUND", "message": "No delivery found for this tracking code." }, "path": "/request/public/track/xyz", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "429": { "description": "Too many requests. Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you can retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 12s." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } }, "500": { "description": "Unexpected error (also returned for a non-numeric id or page). Safe to retry with the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please retry with the same Idempotency-Key." }, "path": "/request/public/createRequestWithUser", "timestamp": "2026-11-03T10:15:30.123Z" } } } } } } } }, "webhooks": { "delivery.created": { "post": { "summary": "A delivery was created.", "description": "Fires once per new delivery, including deliveries you create through the API. A job created through the API is open to bids straight away but still reports `publicStatus: PENDING` at this point; no separate `delivery.published` follows.", "operationId": "webhook_delivery_created", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.created" }, "data": { "$ref": "#/components/schemas/DeliveryCreatedEventData" } } } ] }, "example": { "event": "delivery.created", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "PENDING", "newStatus": "PENDING", "title": "Order #5521", "description": "Two pairs of shoes", "additionalNotes": null, "senderName": "Ada Obi", "senderEmail": "ada@example.com", "sourceCity": "Lagos", "sourceState": "Lagos", "destinationCity": "Ibadan", "destinationState": "Oyo", "offerAmount": 5000, "currency": "NGN", "isNewSender": false, "senderTotalCompletedRequests": 14, "sender": { "userId": 4567, "name": "Ada Obi", "email": "ada@example.com", "mobile": "2348012345678", "country": "NG", "state": "Lagos", "city": "Lagos", "address": "12 Marina Rd", "houseNo": null, "zipcode": null, "latitude": 6.45, "longitude": 3.39 }, "pickup": { "location": "Acme Warehouse", "streetAddress": "12 Marina Rd", "houseNo": null, "locality": "Marina", "city": "Lagos", "state": "Lagos", "country": "NG", "zipCode": null, "latitude": 6.45, "longitude": 3.39, "contactName": "Acme Warehouse", "contactMobile": "2348011111111" }, "dropoff": { "location": "5 Ring Rd", "streetAddress": "5 Ring Rd", "houseNo": null, "locality": null, "city": "Ibadan", "state": "Oyo", "country": "NG", "latitude": 7.38, "longitude": 3.94, "receiverName": "Bola A.", "receiverMobile": "2348098765432" } } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.published": { "post": { "summary": "The job is open to delivery partner agents again.", "description": "Fires when a delivery goes back out for bidding: after a delivery partner agent cancels, after a pickup is rejected, or when a saved draft is published. `publicStatus` is `PENDING` even though delivery partner agents can bid.", "operationId": "webhook_delivery_published", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.published" }, "data": { "$ref": "#/components/schemas/DeliveryPublishedEventData" } } } ] }, "example": { "event": "delivery.published", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "PENDING", "newStatus": "PENDING", "reason": "Package not ready at pickup" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.bid_submitted": { "post": { "summary": "A delivery partner agent bid on the delivery.", "description": "Fires for every new bid and every revised bid. With `autoBidAccept`, a bid at or under `maxBidAmount` is accepted for you; otherwise accept the one you want.", "operationId": "webhook_delivery_bid_submitted", "tags": [ "Bids" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.bid_submitted" }, "data": { "$ref": "#/components/schemas/DeliveryBidSubmittedEventData" } } } ] }, "example": { "event": "delivery.bid_submitted", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "PENDING", "newStatus": "PENDING", "bidId": 9876, "partnerName": "Emeka O.", "partnerRating": 4.6, "bidAmount": 4200, "totalAmountToBePaid": 4620, "currency": "NGN", "vehicleType": "MOTORCYCLE", "comment": "Can pick up in 20 minutes" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.bid_accepted": { "post": { "summary": "A bid was accepted and paid for.", "description": "The delivery partner agent is booked. The fields after `bidId` depend on how the bid was paid: expect any of them to be missing.", "operationId": "webhook_delivery_bid_accepted", "tags": [ "Bids" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.bid_accepted" }, "data": { "$ref": "#/components/schemas/DeliveryBidAcceptedEventData" } } } ] }, "example": { "event": "delivery.bid_accepted", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "ACCEPTED", "newStatus": "ACCEPTED", "bidId": 9876, "partnerName": "Emeka O.", "partnerRating": 4.6, "bidAmount": 4200, "totalAmountToBePaid": 4620, "currency": "NGN", "vehicleType": "MOTORCYCLE" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.codes_issued": { "post": { "summary": "Drop-off code created or regenerated.", "description": "Carries the code the receiver gives the delivery partner agent at drop-off. Fires when a bid is accepted and again with `regenerated: true` whenever the code changes (for example after a rejected drop-off). Always sent, whatever `sendDropOffCode` is set to. **Never log or store this code in plain text.**", "operationId": "webhook_delivery_codes_issued", "tags": [ "Pickup and drop-off" ], "x-sensitive": true, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.codes_issued" }, "data": { "$ref": "#/components/schemas/DeliveryCodesIssuedEventData" } } } ] }, "example": { "event": "delivery.codes_issued", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "ACCEPTED", "newStatus": "ACCEPTED", "dropOffCode": "4821", "bundleDropOffCodes": null, "pickupVerificationSkipped": true, "regenerated": false } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.pickup_verified": { "post": { "summary": "Pickup verified.", "description": "The pickup code was entered, or (with `autoVerifyPickup`) the pickup was verified automatically when the bid was accepted. An auto-verified pickup does not mean the delivery partner agent has the package yet: wait for `delivery.in_transit`.", "operationId": "webhook_delivery_pickup_verified", "tags": [ "Pickup and drop-off" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.pickup_verified" }, "data": { "$ref": "#/components/schemas/DeliveryPickupVerifiedEventData" } } } ] }, "example": { "event": "delivery.pickup_verified", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "ACCEPTED", "newStatus": "ACCEPTED", "autoVerified": true } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.pickup_confirmed": { "post": { "summary": "The delivery partner agent confirmed collecting the package.", "description": "No extra fields.", "operationId": "webhook_delivery_pickup_confirmed", "tags": [ "Pickup and drop-off" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.pickup_confirmed" }, "data": { "$ref": "#/components/schemas/DeliveryPickupConfirmedEventData" } } } ] }, "example": { "event": "delivery.pickup_confirmed", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "ACCEPTED", "newStatus": "ACCEPTED" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.in_transit": { "post": { "summary": "The package is on its way.", "description": "Fires when the delivery moves into transit (once per leg on parcel-centre routes).", "operationId": "webhook_delivery_in_transit", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.in_transit" }, "data": { "$ref": "#/components/schemas/DeliveryInTransitEventData" } } } ] }, "example": { "event": "delivery.in_transit", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "IN_TRANSIT", "newStatus": "IN_TRANSIT", "currentLocation": "DA" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.location_updated": { "post": { "summary": "The delivery partner agent's position.", "description": "At most about once a minute per delivery while a delivery partner agent is assigned.", "operationId": "webhook_delivery_location_updated", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.location_updated" }, "data": { "$ref": "#/components/schemas/DeliveryLocationUpdatedEventData" } } } ] }, "example": { "event": "delivery.location_updated", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "IN_TRANSIT", "newStatus": "IN_TRANSIT", "latitude": 6.5012, "longitude": 3.3654, "estimatedArrivalMinutes": 18, "recordedAt": "2026-11-03T10:42:07Z" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.pickup_rejected": { "post": { "summary": "The pickup failed verification.", "description": "For jobs created through the API, the accepted bid is cancelled, you are refunded (`payment.refund_initiated`) and the job reopens (`delivery.published`). Wait for a new delivery partner agent or cancel.", "operationId": "webhook_delivery_pickup_rejected", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.pickup_rejected" }, "data": { "$ref": "#/components/schemas/DeliveryPickupRejectedEventData" } } } ] }, "example": { "event": "delivery.pickup_rejected", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "AWAITING_BIDS", "newStatus": "AWAITING_BIDS", "reason": "Package larger than described" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.dropoff_rejected": { "post": { "summary": "The drop-off failed verification.", "description": "The delivery partner agent will retry with a new code, which arrives as `delivery.codes_issued` with `regenerated: true`.", "operationId": "webhook_delivery_dropoff_rejected", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.dropoff_rejected" }, "data": { "$ref": "#/components/schemas/DeliveryDropoffRejectedEventData" } } } ] }, "example": { "event": "delivery.dropoff_rejected", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "IN_TRANSIT", "newStatus": "IN_TRANSIT", "reason": "Receiver not available" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.partner_cancelled": { "post": { "summary": "The delivery partner agent cancelled an accepted job.", "description": "The job usually goes back out for bidding next (`delivery.published`).", "operationId": "webhook_delivery_partner_cancelled", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.partner_cancelled" }, "data": { "$ref": "#/components/schemas/DeliveryPartnerCancelledEventData" } } } ] }, "example": { "event": "delivery.partner_cancelled", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "PENDING", "newStatus": "PENDING", "bidId": 9876, "reason": "Vehicle breakdown" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.delivered": { "post": { "summary": "Delivered.", "description": "The receiver has the package. `previousStatus` is missing on some completion paths.", "operationId": "webhook_delivery_delivered", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.delivered" }, "data": { "$ref": "#/components/schemas/DeliveryDeliveredEventData" } } } ] }, "example": { "event": "delivery.delivered", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "DELIVERED", "newStatus": "DELIVERED", "previousStatus": "IN_TRANSIT", "completedAt": "2026-11-03T11:05:12Z" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.returned": { "post": { "summary": "Returned to the sender.", "description": "A return-to-sender job was completed.", "operationId": "webhook_delivery_returned", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.returned" }, "data": { "$ref": "#/components/schemas/DeliveryReturnedEventData" } } } ] }, "example": { "event": "delivery.returned", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "DELIVERED", "newStatus": "DELIVERED", "previousStatus": "IN_TRANSIT", "completedAt": "2026-11-03T15:20:00Z" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.cancelled": { "post": { "summary": "Cancelled.", "description": "The delivery was cancelled by its sender (including `POST /deliveries/{idOrCode}/cancel`).", "operationId": "webhook_delivery_cancelled", "tags": [ "Delivery lifecycle" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.cancelled" }, "data": { "$ref": "#/components/schemas/DeliveryCancelledEventData" } } } ] }, "example": { "event": "delivery.cancelled", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "CANCELLED", "newStatus": "CANCELLED", "previousStatus": "AWAITING_BIDS" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.return_requested": { "post": { "summary": "The delivery partner agent asked to return the package to the sender.", "description": "Sent as a bid with the same fields as `delivery.bid_submitted`.", "operationId": "webhook_delivery_return_requested", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.return_requested" }, "data": { "$ref": "#/components/schemas/DeliveryReturnRequestedEventData" } } } ] }, "example": { "event": "delivery.return_requested", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "IN_TRANSIT", "newStatus": "IN_TRANSIT", "bidId": 9901, "partnerName": "Emeka O.", "partnerRating": 4.6, "bidAmount": 1500, "totalAmountToBePaid": 1650, "currency": "NGN", "vehicleType": "MOTORCYCLE", "comment": "Receiver refused the package" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "delivery.return_agreed": { "post": { "summary": "The return to sender was agreed.", "description": "Same fields as `delivery.bid_submitted`.", "operationId": "webhook_delivery_return_agreed", "tags": [ "Exceptions" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "delivery.return_agreed" }, "data": { "$ref": "#/components/schemas/DeliveryReturnAgreedEventData" } } } ] }, "example": { "event": "delivery.return_agreed", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "requestId": 123, "trackingCode": "DLV-000123", "trackingToken": "q3Zr8Kd0aP1xYt7bWm2cLs4e", "userPhone": "2348012345678", "senderUserId": 4567, "publicStatus": "IN_TRANSIT", "newStatus": "IN_TRANSIT", "bidId": 9901, "partnerName": "Emeka O.", "partnerRating": 4.6, "bidAmount": 1500, "totalAmountToBePaid": 1650, "currency": "NGN", "vehicleType": "MOTORCYCLE", "comment": null } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "payment.required": { "post": { "summary": "A payment link must be paid.", "description": "No wallet balance or saved card covered the bid, so it waits for this link to be paid. Send `paymentUrl` to whoever pays. Links expire after about an hour.", "operationId": "webhook_payment_required", "tags": [ "Payments" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "payment.required" }, "data": { "$ref": "#/components/schemas/PaymentRequiredEventData" } } } ] }, "example": { "event": "payment.required", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userPhone": "2348012345678", "requestId": 123, "trackingCode": "DLV-000123", "bidId": 9876, "amount": 4620, "currency": "NGN", "paymentUrl": "https://checkout.paystack.com/abc123", "reference": "DLV_123_9876", "expiresAt": "2026-11-03T11:30:00Z", "method": "LINK" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "payment.successful": { "post": { "summary": "A payment went through.", "description": "Paid from wallet, card or link. Some payment-link successes only show up as `delivery.bid_accepted`, so treat that event as proof of payment too.", "operationId": "webhook_payment_successful", "tags": [ "Payments" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "payment.successful" }, "data": { "$ref": "#/components/schemas/PaymentSuccessfulEventData" } } } ] }, "example": { "event": "payment.successful", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userPhone": "2348012345678", "requestId": 123, "trackingCode": "DLV-000123", "bidId": 9876, "amount": 4620, "currency": "NGN", "transactionId": "WLT-77812", "method": "WALLET" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "payment.failed": { "post": { "summary": "A payment source couldn't pay.", "description": "Fires for each source that is skipped or fails; the next source is then tried. `reason` is usually one of the listed codes but can be gateway text.", "operationId": "webhook_payment_failed", "tags": [ "Payments" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "payment.failed" }, "data": { "$ref": "#/components/schemas/PaymentFailedEventData" } } } ] }, "example": { "event": "payment.failed", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userPhone": "2348012345678", "requestId": 123, "trackingCode": "DLV-000123", "bidId": 9876, "amount": 4620, "currency": "NGN", "method": "WALLET", "reason": "INSUFFICIENT_WALLET_BALANCE", "retryAllowed": false } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "payment.refund_initiated": { "post": { "summary": "A refund was started.", "description": "Refunds go back to the source that paid. Only identifies the delivery; the amount arrives with `payment.refund_completed`.", "operationId": "webhook_payment_refund_initiated", "tags": [ "Payments" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "payment.refund_initiated" }, "data": { "$ref": "#/components/schemas/PaymentRefundInitiatedEventData" } } } ] }, "example": { "event": "payment.refund_initiated", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userPhone": "2348012345678", "requestId": 123, "trackingCode": "DLV-000123" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "payment.refund_completed": { "post": { "summary": "A refund finished.", "description": "Gateway fees are not refunded on card and link payments.", "operationId": "webhook_payment_refund_completed", "tags": [ "Payments" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "payment.refund_completed" }, "data": { "$ref": "#/components/schemas/PaymentRefundCompletedEventData" } } } ] }, "example": { "event": "payment.refund_completed", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userPhone": "2348012345678", "requestId": 123, "trackingCode": "DLV-000123", "bidId": 9876, "amount": 4620, "currency": "NGN", "transactionId": "RFD-55120" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "account.signup": { "post": { "summary": "A user you onboarded was created.", "description": "Fires when `POST /createRequestWithUser` registers a new sender on your channel.", "operationId": "webhook_account_signup", "tags": [ "Accounts" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "account.signup" }, "data": { "$ref": "#/components/schemas/AccountSignupEventData" } } } ] }, "example": { "event": "account.signup", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userId": 4567, "userPhone": "2348012345678", "mobile": "2348012345678", "email": "ada@example.com", "name": "Ada Obi", "role": "customer", "registrationSource": "ACME", "referralCode": null, "referrerId": null, "referrerMobile": null, "referrerEmail": null, "country": "NG", "state": "Lagos", "city": "Lagos", "address": "12 Marina Rd", "houseNo": null, "zipcode": null, "latitude": 6.45, "longitude": 3.39 } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "account.kyc_required": { "post": { "summary": "A user you onboarded must complete identity checks.", "description": "Only for users registered on your channel.", "operationId": "webhook_account_kyc_required", "tags": [ "Accounts" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "account.kyc_required" }, "data": { "$ref": "#/components/schemas/AccountKycRequiredEventData" } } } ] }, "example": { "event": "account.kyc_required", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userId": 4567, "userPhone": "2348012345678" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "account.kyc_approved": { "post": { "summary": "Identity checks passed.", "description": "Only for users registered on your channel.", "operationId": "webhook_account_kyc_approved", "tags": [ "Accounts" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "account.kyc_approved" }, "data": { "$ref": "#/components/schemas/AccountKycApprovedEventData" } } } ] }, "example": { "event": "account.kyc_approved", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userId": 4567, "userPhone": "2348012345678" } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } }, "account.kyc_rejected": { "post": { "summary": "Identity checks failed.", "description": "Only for users registered on your channel.", "operationId": "webhook_account_kyc_rejected", "tags": [ "Accounts" ], "x-sensitive": false, "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook signing secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "const": "Delivahere-Webhook/1.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "account.kyc_rejected" }, "data": { "$ref": "#/components/schemas/AccountKycRejectedEventData" } } } ] }, "example": { "event": "account.kyc_rejected", "timestamp": "2026-11-03T10:15:30.517Z", "idempotencyKey": "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4", "channel": "ACME", "data": { "userId": 4567, "userPhone": "2348012345678", "reason": "Document unreadable", "retryAllowed": true } } } } }, "responses": { "200": { "description": "Received. Reply **exactly 200**: Delivahere treats any other 2xx as a failure and does not retry it." }, "429": { "description": "Retried, like 5xx." }, "5XX": { "description": "Retried with the same body and `idempotencyKey` (after 2, 4, 8, 16 and 32 seconds)." } } } } }, "components": { "securitySchemes": { "clientId": { "type": "apiKey", "in": "header", "name": "client_id", "description": "Your client ID." }, "secretKey": { "type": "apiKey", "in": "header", "name": "secret_key", "description": "Your secret. Server-side only: never in an app, a browser bundle or a repo." }, "sessionToken": { "type": "apiKey", "in": "header", "name": "X-Session-Token", "description": "Per-user session from `POST /session` (24 hours)." } }, "schemas": { "SuccessEnvelope": { "type": "object", "description": "Every successful response (except `GET /track`). Delivahere returns HTTP 200 for these even when the body's `status` differs, so read the body.", "properties": { "responseMessage": { "type": "string", "description": "Human-readable result." }, "status": { "type": [ "integer", "null" ], "description": "Result code in the body (usually 200; 202 for a pending card payment)." }, "resourceData": { "description": "The result. Its shape depends on the endpoint." }, "totalRecords": { "type": [ "integer", "null" ], "description": "Paginated lists only: total matching items." }, "noOfRecords": { "type": [ "integer", "null" ], "description": "Paginated lists only: items in this page." } }, "additionalProperties": true }, "Error": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable, machine-readable code. Branch on this, not on `message`." }, "message": { "type": "string", "description": "Human-readable detail. Wording can change." }, "requiredFields": { "type": "array", "items": { "type": "string" }, "description": "`USER_REGISTRATION_REQUIRED` only." } } }, "path": { "type": "string", "description": "Request path." }, "timestamp": { "type": "string", "description": "When the error happened.", "format": "date-time" } } }, "GeoPoint": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "description": "WGS84 latitude.", "minimum": -90, "maximum": 90, "examples": [ 6.5244 ] }, "longitude": { "type": "number", "description": "WGS84 longitude.", "minimum": -180, "maximum": 180, "examples": [ 3.3792 ] } } }, "CreateDeliveryRequest": { "type": "object", "required": [ "mobile", "weightClass" ], "properties": { "mobile": { "type": "string", "description": "Sender's phone (`2348012345678`, or national number with `countryCode`). An existing customer is used as-is; a new one needs `fullName` and `email`.", "examples": [ "2348012345678" ] }, "countryCode": { "type": "string", "description": "Country calling code when `mobile` is a national number." }, "fullName": { "type": "string", "description": "New senders only: full name." }, "email": { "type": "string", "description": "New senders only: email. Delivahere emails them their account details.", "format": "email" }, "title": { "type": "string", "description": "Short package title.", "examples": [ "Order #5521" ] }, "description": { "type": "string", "description": "Package description." }, "additionalNotes": { "type": "string", "description": "Notes for the delivery partner agent." }, "pkgType": { "type": "string", "description": "Package type, free text." }, "weightClass": { "type": "string", "enum": [ "light", "medium", "heavy", "extra_heavy" ], "description": "`light` under 5 kg, `medium` 5–15 kg, `heavy` 15–30 kg, `extra_heavy` 30 kg+. Case-insensitive." }, "vehicleType": { "type": "string", "enum": [ "MOTORCYCLE", "BICYCLE", "TRICYCLE", "SEDAN", "SUV", "MINIVAN", "PANEL_VAN", "PICKUP_TRUCK", "MINI_TRUCK_6T", "LIGHT_TRUCK_OPEN", "LIGHT_TRUCK_CONTAINER", "MEDIUM_TRUCK_10T", "MEDIUM_TRUCK_12T", "HEAVY_TRUCK_16T", "HEAVY_TRUCK_18T_CONTAINER", "HEAVY_TRUCK_25T", "EXTRA_HEAVY_30T", "EXTRA_HEAVY_35T", "TRAILER_20FT", "TRAILER_40FT", "NONE_OR_ANY_VEHICLE" ], "description": "Vehicle to request. Case-insensitive; also accepts `CAR`, `VAN`, `SMALL_TRUCK`, `MEDIUM_TRUCK`, `LARGE_TRUCK`, `TRAILER`. Unknown values are `400`. Send it explicitly: there is no default." }, "declaredValueAmount": { "type": "integer", "description": "Declared package value, in whole units of the delivery currency.", "minimum": 0, "examples": [ 50000 ] }, "offerAmount": { "type": "integer", "description": "The price you offer delivery partner agents, in whole units of the delivery currency.", "minimum": 0, "examples": [ 5000 ] }, "currency": { "type": "string", "description": "ISO currency. The pickup country's currency wins when `sourceCountry` is recognised; this is the fallback.", "examples": [ "NGN" ] }, "insured": { "type": "boolean", "description": "Insure the package at its declared value (NGN: declared value of at least ₦50,000). Note the name: `insured`, not `isInsured`.", "default": false }, "sourceLocation": { "type": "string", "description": "Pickup: free-text location / landmark." }, "sourceHouseNo": { "type": "string", "description": "Pickup: house number." }, "sourceStreetAddress": { "type": "string", "description": "Pickup: street address." }, "sourceLocality": { "type": "string", "description": "Pickup: area." }, "sourceCity": { "type": "string", "description": "Pickup: city." }, "sourceState": { "type": "string", "description": "Pickup: state." }, "sourceCountry": { "type": "string", "description": "Pickup: ISO country code. Decides the delivery currency.", "examples": [ "NG" ] }, "sourceLatitude": { "type": "number", "description": "Pickup latitude.", "minimum": -90, "maximum": 90 }, "sourceLongitude": { "type": "number", "description": "Pickup longitude.", "minimum": -180, "maximum": 180 }, "pickupName": { "type": "string", "description": "Pickup contact name." }, "pickupMobile": { "type": "string", "description": "Pickup contact phone.", "x-sensitive": true }, "destinationLocation": { "type": "string", "description": "Drop-off: free-text location / landmark." }, "destinationHouseNo": { "type": "string", "description": "Drop-off: house number." }, "destinationStreetAddress": { "type": "string", "description": "Drop-off: street address." }, "destinationLocality": { "type": "string", "description": "Drop-off: area." }, "destinationCity": { "type": "string", "description": "Drop-off: city." }, "destinationState": { "type": "string", "description": "Drop-off: state." }, "destinationCountry": { "type": "string", "description": "Drop-off: ISO country code.", "examples": [ "NG" ] }, "destinationLatitude": { "type": "number", "description": "Drop-off latitude.", "minimum": -90, "maximum": 90 }, "destinationLongitude": { "type": "number", "description": "Drop-off longitude.", "minimum": -180, "maximum": 180 }, "receiverName": { "type": "string", "description": "Receiver name." }, "receiverMobile": { "type": "string", "description": "Receiver phone.", "x-sensitive": true }, "mediaUrls": { "description": "Package photos: the `url` values returned by `POST /media`, as an array or a comma-separated string.", "oneOf": [ { "type": "array", "items": { "type": "string", "format": "uri" } }, { "type": "string" } ] }, "pickupDate": { "type": "string", "description": "Scheduled pickup date.", "format": "date-time" }, "pickupTime": { "type": "string", "description": "Scheduled pickup time.", "format": "date-time" }, "expectedDeliveryTime": { "type": "string", "description": "Requested delivery time.", "format": "date-time" }, "isPublished": { "type": "boolean", "description": "`false` saves a draft that can't be accepted or cancelled through the API. Leave it out.", "default": true }, "autoVerifyPickup": { "type": "boolean", "description": "Skip the pickup code: the pickup counts as verified when a bid is accepted. Recommended, since you aren't at the handover.", "default": false }, "autoBidAccept": { "type": "boolean", "description": "Accept the first bid at or under `maxBidAmount` automatically and pay for it.", "default": false }, "maxBidAmount": { "type": "number", "description": "Required (> 0) with `autoBidAccept`: the most you'll pay a delivery partner agent.", "exclusiveMinimum": 0 }, "autoBidPaymentMode": { "type": "string", "enum": [ "CARD", "WALLET" ], "description": "With `autoBidAccept`: pay auto-accepted bids from the card or the wallet. `WALLET` reserves the amount at creation (`402` if the balance is short)." }, "notifySender": { "type": "boolean", "description": "`false`: Delivahere sends the sender account no SMS, WhatsApp, email or push about this job. Use it when one business account books every job and you notify customers from webhooks.", "default": true }, "sendDropOffCode": { "type": "boolean", "description": "`false`: Delivahere doesn't text the receiver the drop-off code; you deliver it from `delivery.codes_issued`.", "default": true } } }, "CreateDeliveryResult": { "type": "object", "required": [ "requestId", "trackingCode", "trackingToken", "status", "userId" ], "properties": { "requestId": { "type": "integer", "description": "Delivery ID." }, "deliveryId": { "type": "integer", "description": "Same as `requestId`." }, "trackingCode": { "type": "string", "description": "Display code, e.g. `DLV-000123`." }, "trackingToken": { "type": "string", "description": "Unguessable reference for tracking links. Store it." }, "status": { "type": "string", "description": "Always `PENDING` at creation." }, "currency": { "type": [ "string", "null" ], "description": "Delivery currency." }, "userId": { "type": "integer", "description": "Sender's user ID (new or existing)." }, "delivaPkgProtectedInsurance": { "type": "boolean", "description": "Always false here." }, "mediaUrls": { "type": "array", "description": "Present when photos were attached.", "items": { "type": "object", "properties": { "originalMediaUrl": { "type": "string", "description": "Photo." }, "thumbnailUrl80X80": { "type": "string", "description": "Thumbnail." }, "thumbnailUrl350X350": { "type": "string", "description": "Thumbnail." } } } } } }, "DeliveryListItem": { "type": "object", "description": "Fields that are null are left out.", "properties": { "requestId": { "type": "integer", "description": "Delivery ID." }, "customerId": { "type": "integer", "description": "Sender's user ID." }, "title": { "type": "string", "description": "Package title." }, "status": { "type": "string", "description": "Internal status (not `publicStatus`), e.g. `PUBLISHED`, `ACCEPTED_BID`, `IN_TRANSIT`, `DELIVERED`, `CANCELLED`. Use `GET /deliveries/{idOrCode}` for `publicStatus`." }, "requestType": { "type": "string", "enum": [ "LOCAL", "INTERSTATE", "INTERNATIONAL" ] }, "sourceLocation": { "type": "string", "description": "Pickup." }, "sourceCity": { "type": "string", "description": "Pickup city." }, "destinationLocation": { "type": "string", "description": "Drop-off." }, "destinationCity": { "type": "string", "description": "Drop-off city." }, "daName": { "type": "string", "description": "Name of the last delivery partner agent who bid." }, "deliveryDate": { "type": "string", "description": "When it was delivered.", "format": "date-time" }, "bundle": { "type": "boolean", "description": "Multi-drop job." }, "favourited": { "type": "boolean", "description": "Sender favourited it." } }, "additionalProperties": true }, "DeliveryDetail": { "type": "object", "description": "Full delivery detail for its sender. More fields may appear; ignore what you don't use.", "properties": { "requestId": { "type": "integer", "description": "Delivery ID." }, "customerId": { "type": "integer", "description": "Sender's user ID." }, "title": { "type": [ "string", "null" ], "description": "Title." }, "description": { "type": [ "string", "null" ], "description": "Description." }, "publicStatus": { "$ref": "#/components/schemas/PublicStatus" }, "status": { "type": [ "string", "null" ], "description": "Internal status. Prefer `publicStatus`." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency." }, "value": { "type": "number", "description": "Declared value." }, "bidAmount": { "type": [ "integer", "null" ], "description": "The sender's original **offer** (despite the name)." }, "acceptedBidAmount": { "type": [ "number", "null" ], "description": "Accepted bid amount, once accepted." }, "weightClass": { "type": [ "string", "null" ], "description": "`light`, `medium`, `heavy` or `extra_heavy`." }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type." }, "vehicleTypeLabel": { "type": [ "string", "null" ], "description": "Vehicle display name." }, "sourceLocation": { "type": [ "string", "null" ], "description": "Pickup." }, "sourceStreetAddress": { "type": [ "string", "null" ], "description": "Pickup street." }, "sourceCity": { "type": [ "string", "null" ], "description": "Pickup city." }, "sourceState": { "type": [ "string", "null" ], "description": "Pickup state." }, "sourceCountry": { "type": [ "string", "null" ], "description": "Pickup country." }, "sourceLatitude": { "type": "number", "description": "Pickup latitude." }, "sourceLongitude": { "type": "number", "description": "Pickup longitude." }, "destinationLocation": { "type": [ "string", "null" ], "description": "Drop-off." }, "destinationStreetAddress": { "type": [ "string", "null" ], "description": "Drop-off street." }, "destinationCity": { "type": [ "string", "null" ], "description": "Drop-off city." }, "destinationState": { "type": [ "string", "null" ], "description": "Drop-off state." }, "destinationCountry": { "type": [ "string", "null" ], "description": "Drop-off country." }, "destinationLatitude": { "type": "number", "description": "Drop-off latitude." }, "destinationLongitude": { "type": "number", "description": "Drop-off longitude." }, "senderName": { "type": [ "string", "null" ], "description": "Sender." }, "pickupName": { "type": [ "string", "null" ], "description": "Pickup contact." }, "pickupMobile": { "type": [ "string", "null" ], "description": "Pickup contact phone (`+` prefixed).", "x-sensitive": true }, "receiverName": { "type": [ "string", "null" ], "description": "Receiver." }, "receiverMobile": { "type": [ "string", "null" ], "description": "Receiver phone.", "x-sensitive": true }, "pickupDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Scheduled pickup." }, "expectedDeliveryDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Expected delivery." }, "orderDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Created." }, "partnerCode": { "type": [ "integer", "null" ], "description": "Delivery partner agent's user ID, once a bid is accepted." }, "partnerName": { "type": [ "string", "null" ], "description": "Delivery partner agent's name." }, "partnerContact": { "type": [ "string", "null" ], "description": "Delivery partner agent's phone.", "x-sensitive": true }, "partnerProfileImageUrl": { "type": [ "string", "null" ], "description": "Delivery partner agent's photo." }, "pickupCode": { "type": [ "string", "null" ], "description": "Pickup code. Treat as a secret.", "x-sensitive": true }, "dropOffCode": { "type": [ "string", "null" ], "description": "Drop-off code. Treat as a secret.", "x-sensitive": true }, "orderCancelReason": { "type": [ "string", "null" ], "description": "Cancellation reason." }, "isBundle": { "type": "boolean", "description": "Multi-drop job." } }, "additionalProperties": true }, "Timeline": { "type": "object", "properties": { "requestId": { "type": "integer", "description": "Delivery ID." }, "title": { "type": [ "string", "null" ], "description": "Title." }, "requestType": { "type": [ "string", "null" ], "description": "`LOCAL`, `INTERSTATE` or `INTERNATIONAL`." }, "expectedDeliveryDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Expected delivery." }, "docketNumber": { "type": "string", "description": "Parcel-centre docket (`0` when none)." }, "opcDetail": { "$ref": "#/components/schemas/TimelineLeg" }, "daDetail": { "$ref": "#/components/schemas/TimelineLeg" }, "dpcDetail": { "$ref": "#/components/schemas/TimelineLeg" }, "rcDetail": { "$ref": "#/components/schemas/TimelineLeg" } } }, "TimelineLeg": { "type": [ "object", "null" ], "description": "The latest transit on this leg: `opc` origin parcel centre, `da` with the delivery partner agent, `dpc` destination parcel centre, `rc` receiver.", "properties": { "transitDate": { "type": [ "string", "null" ], "format": "date-time", "description": "When the package reached this leg." }, "mediaUrls": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "Bid": { "type": "object", "description": "One delivery partner agent bid. More fields may appear; ignore what you don't use.", "properties": { "bidId": { "type": "integer", "description": "Bid ID. Accept with `POST /deliveries/{idOrCode}/bids/{bidId}/accept`." }, "daId": { "type": "integer", "description": "Delivery partner agent's user ID." }, "name": { "type": [ "string", "null" ], "description": "Delivery partner agent's name." }, "rating": { "type": "number", "description": "Delivery partner agent's average rating." }, "bidAmount": { "type": "number", "description": "The delivery partner agent's price." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency." }, "comment": { "type": [ "string", "null" ], "description": "Delivery partner agent's note." }, "totalAmountToBePaid": { "type": "string", "description": "What accepting this bid costs in total, as numeric text (e.g. `\"4620\"`, `\"12.50\"`).", "examples": [ "4620" ] }, "platformFee": { "type": "number", "description": "Platform fee." }, "insuranceAmount": { "type": "number", "description": "Insurance amount." }, "vehicleType": { "type": [ "string", "null" ], "description": "Delivery partner agent's vehicle." }, "vehicleTypeLabel": { "type": [ "string", "null" ], "description": "Vehicle display name." }, "profileImageUrl": { "type": [ "string", "null" ], "description": "Delivery partner agent's photo." }, "pickupDateAndTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Delivery partner agent's proposed pickup time." }, "expectedDateAndTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Delivery partner agent's proposed delivery time." }, "partnerDistanceFromPickupKm": { "type": "number", "description": "Delivery partner agent's distance from the pickup, when known." } }, "additionalProperties": true }, "PriceRange": { "type": "object", "required": [ "low", "optimal", "high", "currency" ], "properties": { "low": { "type": "number", "description": "Lower bound (0.80 × optimal)." }, "optimal": { "type": "number", "description": "Recommended offer." }, "high": { "type": "number", "description": "Upper bound (1.50 × optimal)." }, "currency": { "type": "string", "description": "ISO currency." }, "distance": { "type": "object", "properties": { "value": { "type": "number", "description": "Distance." }, "unit": { "type": "string", "enum": [ "Km", "Mi" ] } } } } }, "PriceEstimate": { "type": "object", "required": [ "low", "optimal", "high", "currency" ], "properties": { "low": { "type": "number", "description": "Lower bound." }, "optimal": { "type": "number", "description": "Recommended offer." }, "high": { "type": "number", "description": "Upper bound." }, "currency": { "type": "string", "description": "ISO currency." }, "confidence": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "description": "How specific the pricing data for this route is." }, "configScope": { "type": "string", "enum": [ "LOCALITY_PAIR", "CITY_PAIR", "CITY", "STATE", "COUNTRY", "CURRENCY", "GLOBAL" ] }, "distance": { "type": "object", "properties": { "value": { "type": "number", "description": "Distance." }, "unit": { "type": "string", "description": "`Km` or `Mi`." }, "timeMinutes": { "type": "integer", "description": "Estimated travel time." }, "source": { "type": "string", "description": "How distance was measured." } } }, "vehicleType": { "type": "string", "description": "Vehicle the price is for." }, "vehicleInferred": { "type": "boolean", "description": "True when Delivahere picked the vehicle." }, "cost": { "type": "object", "description": "`baseFare + distanceCost + weightCost = subtotal`; `subtotal × factorsMultiplier (+ pcCharge) = total` (= `optimal`).", "properties": { "baseFare": { "type": "number", "description": "" }, "distanceCost": { "type": "number", "description": "" }, "weightCost": { "type": "number", "description": "" }, "subtotal": { "type": "number", "description": "" }, "factorsMultiplier": { "type": "number", "description": "" }, "pcCharge": { "type": "number", "description": "Parcel-centre charge." }, "total": { "type": "number", "description": "" } } }, "factors": { "type": "object", "additionalProperties": true, "description": "Multipliers applied (vehicle, item value, time of day)." }, "eligibleVehicles": { "type": "array", "items": { "type": "object", "properties": { "vehicleType": { "type": "string", "description": "Vehicle." }, "displayName": { "type": "string", "description": "Name." }, "low": { "type": "number", "description": "" }, "mid": { "type": "number", "description": "" }, "high": { "type": "number", "description": "" }, "maxWeightKg": { "type": "number", "description": "" }, "suitable": { "type": "boolean", "description": "" }, "recommended": { "type": "boolean", "description": "" } }, "additionalProperties": true } }, "excludedVehicles": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Vehicle." }, "reason": { "type": "string", "enum": [ "WEIGHT_EXCEEDED", "DISTANCE_EXCEEDED" ] } }, "additionalProperties": true } }, "estimationId": { "type": "string", "description": "Reference for this estimate." }, "expiresAt": { "type": "string", "description": "Estimate guidance is valid for about 10 minutes.", "format": "date-time" } }, "additionalProperties": true }, "PublicTracking": { "type": "object", "description": "Redacted tracking view, safe to show anyone with the link.", "properties": { "trackingCode": { "type": "string", "description": "Display code." }, "status": { "$ref": "#/components/schemas/PublicStatus" }, "title": { "type": [ "string", "null" ], "description": "Title." }, "senderName": { "type": [ "string", "null" ], "description": "Sender, as \"First L.\"." }, "receiverName": { "type": [ "string", "null" ], "description": "Receiver, as \"First L.\"." }, "sourceLocation": { "type": [ "string", "null" ], "description": "Pickup, city level." }, "destinationLocation": { "type": [ "string", "null" ], "description": "Drop-off, city level." }, "sourceLatitude": { "type": "number", "description": "Pickup, rounded to 2 decimals." }, "sourceLongitude": { "type": "number", "description": "Pickup, rounded to 2 decimals." }, "destinationLatitude": { "type": "number", "description": "Drop-off, rounded to 2 decimals." }, "destinationLongitude": { "type": "number", "description": "Drop-off, rounded to 2 decimals." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Created." }, "estimatedDelivery": { "type": [ "string", "null" ], "format": "date-time", "description": "Expected delivery." }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Delivered." }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cancelled." }, "cancellationReason": { "type": [ "string", "null" ], "description": "Why it was cancelled." }, "streamChannel": { "type": [ "string", "null" ], "description": "Live-update channel name, when live tracking is on." }, "partner": { "type": [ "object", "null" ], "description": "The delivery partner agent, once booked.", "properties": { "name": { "type": [ "string", "null" ], "description": "Delivery partner agent's name." }, "contact": { "type": [ "string", "null" ], "description": "Masked phone, e.g. `+234 *** *** 5678`." }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type." }, "latitude": { "type": [ "number", "null" ], "description": "Live position." }, "longitude": { "type": [ "number", "null" ], "description": "Live position." }, "estimatedArrivalMinutes": { "type": [ "integer", "null" ], "description": "Minutes to arrival." }, "etaConfidence": { "type": [ "string", "null" ], "description": "`medium` or `low`." } } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "Public status at this point." }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "When." }, "message": { "type": "string", "description": "Human-readable description." }, "location": { "type": [ "object", "null" ], "properties": { "locationType": { "type": "string", "enum": [ "sender", "receiver", "parcel_center", "partner" ] }, "locationLabel": { "type": [ "string", "null" ], "description": "Label." }, "latitude": { "type": [ "number", "null" ], "description": "" }, "longitude": { "type": [ "number", "null" ], "description": "" } } } } } }, "notices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Notice ID." }, "type": { "type": "string", "description": "`payment_required`, `customs_hold`, `return_fee`, `address_correction` or `info`." }, "title": { "type": [ "string", "null" ], "description": "" }, "message": { "type": [ "string", "null" ], "description": "" }, "actionUrl": { "type": [ "string", "null" ], "description": "" }, "actionLabel": { "type": [ "string", "null" ], "description": "" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "" } } } } }, "additionalProperties": true }, "PublicStatus": { "type": "string", "enum": [ "PENDING", "AWAITING_BIDS", "ACCEPTED", "PICKED_UP", "IN_TRANSIT", "DELIVERED", "CANCELLED" ], "description": "Stable, partner-facing delivery status. Build your logic on this, not on internal statuses. Treat an unknown value as \"no change\" rather than failing." }, "WebhookEnvelope": { "type": "object", "required": [ "event", "timestamp", "idempotencyKey", "channel", "data" ], "properties": { "event": { "type": "string", "description": "Event name, e.g. `delivery.bid_accepted`." }, "timestamp": { "type": "string", "description": "When Delivahere dispatched the event (UTC, RFC 3339). Milliseconds are left out when they are zero, so parse it as RFC 3339 rather than a fixed pattern. Retries reuse the same value.", "format": "date-time", "examples": [ "2026-11-03T09:15:42.517Z" ] }, "idempotencyKey": { "type": "string", "description": "Unique per event and the same on every retry. De-duplicate on it.", "pattern": "^evt_[0-9a-f-]{36}$", "examples": [ "evt_3f1c2a9e-5b7d-4e1a-9c33-0d2b8f6a71e4" ] }, "channel": { "type": [ "string", "null" ], "description": "The channel the delivery or user belongs to (your channel for your own jobs)." }, "data": { "type": "object", "description": "Event payload; see each event." } } }, "WebhookPickup": { "type": "object", "properties": { "location": { "type": [ "string", "null" ], "description": "Free-text pickup location." }, "streetAddress": { "type": [ "string", "null" ], "description": "Street address." }, "houseNo": { "type": [ "string", "null" ], "description": "House number." }, "locality": { "type": [ "string", "null" ], "description": "Locality / area." }, "city": { "type": [ "string", "null" ], "description": "City." }, "state": { "type": [ "string", "null" ], "description": "State." }, "country": { "type": [ "string", "null" ], "description": "Country." }, "zipCode": { "type": [ "string", "null" ], "description": "Postal code." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude." }, "contactName": { "type": [ "string", "null" ], "description": "Pickup contact name." }, "contactMobile": { "type": [ "string", "null" ], "description": "Pickup contact phone, international digits without `+`.", "x-sensitive": true } } }, "WebhookDropoff": { "type": "object", "description": "Drop-off point. Multi-drop stops also carry `dropOffId`, `sequenceNo` and `zipCode`.", "properties": { "dropOffId": { "type": "integer", "description": "Multi-drop only: the stop ID." }, "sequenceNo": { "type": "integer", "description": "Multi-drop only: the stop's position in the route." }, "location": { "type": [ "string", "null" ], "description": "Free-text drop-off location." }, "streetAddress": { "type": [ "string", "null" ], "description": "Street address." }, "houseNo": { "type": [ "string", "null" ], "description": "House number." }, "locality": { "type": [ "string", "null" ], "description": "Locality / area." }, "city": { "type": [ "string", "null" ], "description": "City." }, "state": { "type": [ "string", "null" ], "description": "State." }, "country": { "type": [ "string", "null" ], "description": "Country." }, "zipCode": { "type": [ "string", "null" ], "description": "Multi-drop only: postal code." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude." }, "receiverName": { "type": [ "string", "null" ], "description": "Receiver name.", "x-sensitive": true }, "receiverMobile": { "type": [ "string", "null" ], "description": "Receiver phone, international digits without `+`.", "x-sensitive": true } } }, "DeliveryEventCommon": { "type": "object", "description": "Fields every `delivery.*` event carries.", "required": [ "requestId", "trackingCode", "publicStatus", "newStatus" ], "properties": { "requestId": { "type": "integer", "description": "Delivery ID.", "examples": [ 123 ] }, "trackingCode": { "type": "string", "description": "Human-readable code for display, e.g. `DLV-000123`. Not for links.", "examples": [ "DLV-000123" ] }, "trackingToken": { "type": [ "string", "null" ], "description": "Unguessable 24-character reference for tracking links (`GET /track/{trackingToken}`). Can be null on `delivery.created`; read it from the create response instead.", "examples": [ "q3Zr8Kd0aP1xYt7bWm2cLs4e" ] }, "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone, E.164 without `+`.", "examples": [ "2348012345678" ] }, "senderUserId": { "type": [ "integer", "null" ], "description": "Sender's user ID." }, "publicStatus": { "$ref": "#/components/schemas/PublicStatus" }, "newStatus": { "$ref": "#/components/schemas/PublicStatus", "description": "Same value as `publicStatus` (kept for older integrations)." } } }, "DeliveryCreatedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "Package title." }, "description": { "type": [ "string", "null" ], "description": "Package description." }, "additionalNotes": { "type": [ "string", "null" ], "description": "Free-text notes for the delivery partner agent." }, "senderName": { "type": [ "string", "null" ], "description": "Sender's name." }, "senderEmail": { "type": [ "string", "null" ], "description": "Sender's email.", "x-sensitive": true }, "sourceCity": { "type": [ "string", "null" ], "description": "Pickup city." }, "sourceState": { "type": [ "string", "null" ], "description": "Pickup state." }, "destinationCity": { "type": [ "string", "null" ], "description": "Drop-off city." }, "destinationState": { "type": [ "string", "null" ], "description": "Drop-off state." }, "offerAmount": { "type": "number", "description": "The sender's offered price, in major units." }, "currency": { "type": "string", "description": "ISO currency code." }, "isNewSender": { "type": "boolean", "description": "True when the sender has no completed deliveries yet." }, "senderTotalCompletedRequests": { "type": "integer", "description": "How many deliveries this sender has completed." }, "sender": { "type": "object", "description": "The sender account.", "properties": { "userId": { "type": "integer", "description": "Sender's user ID." }, "name": { "type": [ "string", "null" ], "description": "Name." }, "email": { "type": [ "string", "null" ], "description": "Email.", "x-sensitive": true }, "mobile": { "type": [ "string", "null" ], "description": "Phone, E.164 without `+`.", "x-sensitive": true }, "country": { "type": [ "string", "null" ], "description": "Country." }, "state": { "type": [ "string", "null" ], "description": "State." }, "city": { "type": [ "string", "null" ], "description": "City." }, "address": { "type": [ "string", "null" ], "description": "Street address." }, "houseNo": { "type": [ "string", "null" ], "description": "House number." }, "zipcode": { "type": [ "string", "null" ], "description": "Postal code." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude." } } }, "pickup": { "$ref": "#/components/schemas/WebhookPickup" }, "dropoff": { "$ref": "#/components/schemas/WebhookDropoff", "description": "The drop-off (the first stop on a multi-drop job)." }, "dropoffs": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDropoff" }, "description": "Multi-drop jobs only, in route order. Absent on single-drop jobs." } } } ] }, "DeliveryPublishedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Why it was reopened (after a rejected pickup)." } } } ] }, "DeliveryBidSubmittedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "bidId": { "type": "integer", "description": "Bid ID. Use it with `POST /deliveries/{idOrCode}/bids/{bidId}/accept`." }, "partnerName": { "type": [ "string", "null" ], "description": "Delivery partner agent's display name." }, "partnerRating": { "type": "number", "description": "Delivery partner agent's average rating (0 when unrated)." }, "bidAmount": { "type": "number", "description": "The delivery partner agent's price, in major currency units." }, "totalAmountToBePaid": { "type": "number", "description": "What accepting this bid costs in total, fees included." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code.", "examples": [ "NGN" ] }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type of the delivery.", "examples": [ "MOTORCYCLE" ] }, "comment": { "type": [ "string", "null" ], "description": "Delivery partner agent's note on the bid." } }, "required": [ "bidId" ] } ] }, "DeliveryBidAcceptedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "bidId": { "type": "integer", "description": "Bid ID. Use it with `POST /deliveries/{idOrCode}/bids/{bidId}/accept`." }, "partnerName": { "type": [ "string", "null" ], "description": "Delivery partner agent's display name." }, "partnerRating": { "type": "number", "description": "Delivery partner agent's average rating (0 when unrated)." }, "bidAmount": { "type": "number", "description": "The delivery partner agent's price, in major currency units." }, "totalAmountToBePaid": { "type": "number", "description": "What accepting this bid costs in total, fees included." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code.", "examples": [ "NGN" ] }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type of the delivery.", "examples": [ "MOTORCYCLE" ] }, "comment": { "type": [ "string", "null" ], "description": "Delivery partner agent's note on the bid." }, "partnerPhone": { "type": [ "string", "null" ], "description": "Delivery partner agent's phone (on payment-link and card payments only).", "x-sensitive": true } }, "required": [ "bidId" ] } ] }, "DeliveryCodesIssuedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "dropOffCode": { "type": [ "string", "null" ], "description": "Single-drop jobs: the drop-off code. Null on multi-drop jobs.", "x-sensitive": true }, "bundleDropOffCodes": { "type": [ "array", "null" ], "description": "Multi-drop jobs: one code per stop, in route order. Null on single-drop jobs.", "items": { "type": "object", "properties": { "dropOffId": { "type": "integer", "description": "Stop ID." }, "code": { "type": "string", "description": "Drop-off code for this stop.", "x-sensitive": true } } } }, "pickupVerificationSkipped": { "type": "boolean", "description": "True when the job was created with `autoVerifyPickup`." }, "regenerated": { "type": "boolean", "description": "True when this replaces an earlier code." } } } ] }, "DeliveryPickupVerifiedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "autoVerified": { "type": "boolean", "description": "Present and true when no code was entered." } } } ] }, "DeliveryPickupConfirmedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": {} } ] }, "DeliveryInTransitEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "currentLocation": { "type": [ "string", "null" ], "enum": [ "OPC", "DPC", "DA", "RC", "CUST", null ], "description": "Where the package is: `OPC` origin parcel centre, `DA` with the delivery partner agent, `DPC` destination parcel centre." } } } ] }, "DeliveryLocationUpdatedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "latitude": { "type": "number", "description": "Latitude (never 0,0).", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "description": "Longitude.", "minimum": -180, "maximum": 180 }, "estimatedArrivalMinutes": { "type": [ "integer", "null" ], "description": "Estimated minutes to the drop-off." }, "recordedAt": { "type": "string", "description": "When the position was recorded.", "format": "date-time" } }, "required": [ "latitude", "longitude", "recordedAt" ] } ] }, "DeliveryPickupRejectedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Why it was rejected." } } } ] }, "DeliveryDropoffRejectedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Why it was rejected." } } } ] }, "DeliveryPartnerCancelledEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "bidId": { "type": "integer", "description": "The cancelled bid." }, "reason": { "type": [ "string", "null" ], "description": "Delivery partner agent's reason(s), comma-separated." } } } ] }, "DeliveryDeliveredEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "previousStatus": { "$ref": "#/components/schemas/PublicStatus" }, "completedAt": { "description": "When the delivery finished. Usually an RFC 3339 string; some completion paths send epoch milliseconds. Accept both.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "description": "Epoch milliseconds." } ] } } } ] }, "DeliveryReturnedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "previousStatus": { "$ref": "#/components/schemas/PublicStatus" }, "completedAt": { "description": "When the delivery finished. Usually an RFC 3339 string; some completion paths send epoch milliseconds. Accept both.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "description": "Epoch milliseconds." } ] } } } ] }, "DeliveryCancelledEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "previousStatus": { "$ref": "#/components/schemas/PublicStatus" } } } ] }, "DeliveryReturnRequestedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "bidId": { "type": "integer", "description": "Bid ID. Use it with `POST /deliveries/{idOrCode}/bids/{bidId}/accept`." }, "partnerName": { "type": [ "string", "null" ], "description": "Delivery partner agent's display name." }, "partnerRating": { "type": "number", "description": "Delivery partner agent's average rating (0 when unrated)." }, "bidAmount": { "type": "number", "description": "The delivery partner agent's price, in major currency units." }, "totalAmountToBePaid": { "type": "number", "description": "What accepting this bid costs in total, fees included." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code.", "examples": [ "NGN" ] }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type of the delivery.", "examples": [ "MOTORCYCLE" ] }, "comment": { "type": [ "string", "null" ], "description": "Delivery partner agent's note on the bid." } }, "required": [ "bidId" ] } ] }, "DeliveryReturnAgreedEventData": { "allOf": [ { "$ref": "#/components/schemas/DeliveryEventCommon" }, { "type": "object", "properties": { "bidId": { "type": "integer", "description": "Bid ID. Use it with `POST /deliveries/{idOrCode}/bids/{bidId}/accept`." }, "partnerName": { "type": [ "string", "null" ], "description": "Delivery partner agent's display name." }, "partnerRating": { "type": "number", "description": "Delivery partner agent's average rating (0 when unrated)." }, "bidAmount": { "type": "number", "description": "The delivery partner agent's price, in major currency units." }, "totalAmountToBePaid": { "type": "number", "description": "What accepting this bid costs in total, fees included." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code.", "examples": [ "NGN" ] }, "vehicleType": { "type": [ "string", "null" ], "description": "Vehicle type of the delivery.", "examples": [ "MOTORCYCLE" ] }, "comment": { "type": [ "string", "null" ], "description": "Delivery partner agent's note on the bid." } }, "required": [ "bidId" ] } ] }, "PaymentRequiredEventData": { "type": "object", "properties": { "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone. Usually E.164 without `+`; match on `requestId`, not on this." }, "requestId": { "type": [ "integer", "null" ], "description": "Delivery ID the payment belongs to." }, "trackingCode": { "type": "string", "description": "Delivery tracking code (present when `requestId` is)." }, "bidId": { "type": "integer", "description": "Bid being paid for." }, "amount": { "type": [ "number", "null" ], "description": "Amount in major currency units." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code." }, "paymentUrl": { "type": "string", "description": "Hosted payment page.", "format": "uri" }, "reference": { "type": "string", "description": "Payment reference (missing for some gateways)." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the link expires, when known." }, "method": { "type": [ "string", "null" ], "enum": [ "WALLET", "CARD", "LINK", null ], "description": "`LINK` (missing for some gateways)." } }, "required": [ "bidId", "paymentUrl" ] }, "PaymentSuccessfulEventData": { "type": "object", "properties": { "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone. Usually E.164 without `+`; match on `requestId`, not on this." }, "requestId": { "type": [ "integer", "null" ], "description": "Delivery ID the payment belongs to." }, "trackingCode": { "type": "string", "description": "Delivery tracking code (present when `requestId` is)." }, "bidId": { "type": "integer", "description": "Bid being paid for." }, "amount": { "type": [ "number", "null" ], "description": "Amount in major currency units." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code." }, "transactionId": { "type": "string", "description": "Gateway or wallet transaction ID." }, "method": { "type": [ "string", "null" ], "enum": [ "WALLET", "CARD", "LINK", null ], "description": "Payment source." } }, "required": [ "bidId" ] }, "PaymentFailedEventData": { "type": "object", "properties": { "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone. Usually E.164 without `+`; match on `requestId`, not on this." }, "requestId": { "type": [ "integer", "null" ], "description": "Delivery ID the payment belongs to." }, "trackingCode": { "type": "string", "description": "Delivery tracking code (present when `requestId` is)." }, "bidId": { "type": "integer", "description": "Bid being paid for." }, "amount": { "type": [ "number", "null" ], "description": "Amount in major currency units." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code." }, "transactionId": { "type": "string", "description": "Gateway transaction ID, when there is one." }, "method": { "type": [ "string", "null" ], "enum": [ "WALLET", "CARD", "LINK", null ], "description": "Payment source." }, "reason": { "type": "string", "description": "Why it failed. Known codes: `INSUFFICIENT_WALLET_BALANCE`, `NO_WALLET`, `NO_SAVED_CARD`, `CARD_DECLINED`, `GATEWAY_FAILED`. Other values are gateway messages.", "examples": [ "INSUFFICIENT_WALLET_BALANCE" ] }, "retryAllowed": { "type": "boolean", "description": "Whether retrying the same source can work." } } }, "PaymentRefundInitiatedEventData": { "type": "object", "properties": { "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone. Usually E.164 without `+`; match on `requestId`, not on this." }, "requestId": { "type": [ "integer", "null" ], "description": "Delivery ID the payment belongs to." }, "trackingCode": { "type": "string", "description": "Delivery tracking code (present when `requestId` is)." } } }, "PaymentRefundCompletedEventData": { "type": "object", "properties": { "userPhone": { "type": [ "string", "null" ], "description": "Sender's phone. Usually E.164 without `+`; match on `requestId`, not on this." }, "requestId": { "type": [ "integer", "null" ], "description": "Delivery ID the payment belongs to." }, "trackingCode": { "type": "string", "description": "Delivery tracking code (present when `requestId` is)." }, "bidId": { "type": "integer", "description": "Bid being paid for." }, "amount": { "type": [ "number", "null" ], "description": "Amount in major currency units." }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code." }, "transactionId": { "type": "string", "description": "Refund reference." } } }, "AccountSignupEventData": { "type": "object", "properties": { "userId": { "type": "integer", "description": "New user's ID." }, "userPhone": { "type": [ "string", "null" ], "description": "Phone, E.164 without `+`.", "x-sensitive": true }, "mobile": { "type": [ "string", "null" ], "description": "Same as `userPhone`.", "x-sensitive": true }, "email": { "type": [ "string", "null" ], "description": "Email.", "x-sensitive": true }, "name": { "type": [ "string", "null" ], "description": "Name." }, "role": { "type": [ "string", "null" ], "description": "Account role, e.g. `customer`." }, "registrationSource": { "type": [ "string", "null" ], "description": "Where the account was created (your channel)." }, "referralCode": { "type": [ "string", "null" ], "description": "Referral code used, if any." }, "referrerId": { "type": [ "integer", "null" ], "description": "Referrer's user ID, if any." }, "referrerMobile": { "type": [ "string", "null" ], "description": "Referrer's phone, if any." }, "referrerEmail": { "type": [ "string", "null" ], "description": "Referrer's email, if any." }, "country": { "type": [ "string", "null" ], "description": "Country." }, "state": { "type": [ "string", "null" ], "description": "State." }, "city": { "type": [ "string", "null" ], "description": "City." }, "address": { "type": [ "string", "null" ], "description": "Street address." }, "houseNo": { "type": [ "string", "null" ], "description": "House number." }, "zipcode": { "type": [ "string", "null" ], "description": "Postal code." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude (null when unset)." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude (null when unset)." } }, "required": [ "userId" ] }, "AccountKycRequiredEventData": { "type": "object", "properties": { "userId": { "type": "integer", "description": "User ID." }, "userPhone": { "type": [ "string", "null" ], "description": "Phone." } }, "required": [ "userId" ] }, "AccountKycApprovedEventData": { "type": "object", "properties": { "userId": { "type": "integer", "description": "User ID." }, "userPhone": { "type": [ "string", "null" ], "description": "Phone." } }, "required": [ "userId" ] }, "AccountKycRejectedEventData": { "type": "object", "properties": { "userId": { "type": "integer", "description": "User ID." }, "userPhone": { "type": [ "string", "null" ], "description": "Phone." }, "reason": { "type": "string", "description": "Why it was rejected (absent when no reason was given)." }, "retryAllowed": { "type": "boolean", "description": "Whether the user may resubmit documents." } }, "required": [ "userId" ] } } } }