Shipments
Book a shipment from a quote
POST/shipments
Scope shipments.writeIdempotency-Key required
TEST simulates; LIVE books. A LIVE booking needs a verified Business owner (NB04). BUSINESS_WALLET needs wallet.spend too. No API call silently starts a gateway charge. A checkout selection attached to a LIVE order (NB16) is refused with 409 CHECKOUT_SELECTION_ATTACHED: ship that order instead.
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 BookingRequest
| Field | Type | Description |
|---|---|---|
quoteIdOptional | string | Quote IDPattern ^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$ |
descriptionRequired | string | 3–500 characters |
senderRequired | Contact | |
receiverRequired | Contact | |
paymentModeOptional | enum | One of PREPAID, PAY_ON_PICKUP, BUSINESS_INVOICE, BUSINESS_WALLET |
orderReferenceOptional | string | Business order reference, unique per Business.Pattern ^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$ |
prohibitedItemsDeclarationRequired | Declaration | |
checkoutSelectionOptional | string | NB15: the signed selection token from the checkout widget, in place of quoteId. Verified and used once; the quote, price and point come from it, and the checkout session's order reference is used when orderReference is not sent.0–8000 characters |
Response
| Status | Meaning |
|---|---|
200 | Replay |
201 | Booked |
The body is { "status": "success", "data": … }. Fields of data (BookingResult):
| Field | Type | Description |
|---|---|---|
shipmentRequired | BookedShipment | |
replayedRequired | boolean | |
simulatedOptional | boolean | |
environmentRequired | Environment | The key environment. TEST never touches live custody, payments, dispatch or notifications. |
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). |
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. |