Quotes
Quote one product
POST/quotes
Scope quotes.writeIdempotency-Key required
Prices one product for a parcel and route with the published tariff (and your contract, if any). The quote is frozen until expires_at; book it with its public_id. TEST keys get the same price as LIVE.
Request
Headers
| Name | In | Type | Description |
|---|---|---|---|
AuthorizationRequired | header | string | Bearer <API key> |
Idempotency-KeyRequired | header | string | 8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409. See Idempotency.Pattern ^[A-Za-z0-9._:-]{8,160}$ |
Body QuoteRequest
| Field | Type | Description |
|---|---|---|
marketOptional | MarketCode | Two-letter market (country network) code. Ghana (GH) is live; each market is a separate domestic network. |
serviceOptional | enum | One of EXPRESS, RELAY |
serviceVariantOptional | string | Relay: POINT_TO_POINT or POINT_TO_LOCKER. Express: STANDARD or PRIORITY. |
serviceCodeOptional | ServiceCode | Stable product code (NB02). |
measurementsOptional | Measurements | |
originLocationCodeOptional | string | Relay drop-off point. |
destinationLocationCodeOptional | string | Relay pickup point or locker. |
fallbackLocationCodeOptional | string | Relay Home: the fallback Qoene Point used if the one home attempt fails. Omit it and Qoene picks the nearest suitable point. |
originAddressTextOptional | string | Express pickup address. |
destinationAddressTextOptional | string | Express or Relay Home delivery address. |
destinationPlaceIdOptional | string | |
deliveryInstructionsOptional | string | 0–500 characters |
requestedPickupAtOptional | string (date-time) | Express pickup time; for Relay the planned drop-off time. 30 minutes to 14 days ahead; default now. |
payOnPickupOptional | boolean | |
promotionCodeOptional | string | Pattern ^[A-Za-z0-9_-]{3,32}$ |
Response
| Status | Meaning |
|---|---|
200 | Replay of the original quote |
201 | Quote created |
The body is { "status": "success", "data": … }. Fields of data (QuoteResult):
| Field | Type | Description |
|---|---|---|
quoteRequired | Quote | |
replayedRequired | boolean | |
environmentRequired | Environment | The key environment. TEST never touches live custody, payments, dispatch or notifications. |
simulatedRequired | boolean |
Errors
Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.
| Status | When |
|---|---|
400 | The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed. |
401 | Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked. |
403 | The key lacks the scope, or the operation needs a LIVE key. The key lacks the scope, or this call needs a LIVE key (LIVE_KEY_REQUIRED), or the Business owner is not verified (SENDER_VERIFICATION_REQUIRED). |
404 | Not found for this Business and environment. IDs from another Business or environment are always 404. Not found for this Business and environment. IDs from another Business or the other environment are always 404. |
409 | Idempotency key reused with another body, or the resource changed state. The idempotency key was used with a different body, a reference is already taken, or the resource changed state. |
422 | Eligibility or business rule refused the request; details.reason explains why. A business rule refused the request. details.reason.code says why (for example OVER_PRODUCT_WEIGHT_LIMIT or a point exclusion reason). |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |