Developers
API referenceBusiness sign in

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

Request headers
NameInTypeDescription
AuthorizationRequiredheaderstringBearer <API key>
Idempotency-KeyRequiredheaderstring8–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

Request body
FieldTypeDescription
quoteIdOptionalstringQuote IDPattern ^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$
descriptionRequiredstring3–500 characters
senderRequiredContact
receiverRequiredContact
paymentModeOptionalenumOne of PREPAID, PAY_ON_PICKUP, BUSINESS_INVOICE, BUSINESS_WALLET
orderReferenceOptionalstringBusiness order reference, unique per Business.Pattern ^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$
prohibitedItemsDeclarationRequiredDeclaration
checkoutSelectionOptionalstringNB15: 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

Success responses
StatusMeaning
200Replay
201Booked

The body is { "status": "success", "data": … }. Fields of data (BookingResult):

Response data
FieldTypeDescription
shipmentRequiredBookedShipment
replayedRequiredboolean
simulatedOptionalboolean
environmentRequiredEnvironmentThe key environment. TEST never touches live custody, payments, dispatch or notifications.

Errors

Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.

Error responses
StatusWhen
400The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed.
401Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked.
403The 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).
409Idempotency 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.
422Eligibility 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).
429Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key.