Orders
Ship one order
POST/orders/{orderId}/ship
Scope orders.shipLIVE keys onlyIdempotency-Key required
Queues the same background ship run as the Business inbox (NB11): quote, booking as the verified Business owner, first label when the parcel is ready. An order with a checkout selection (NB16) books the selection quote at the shopper price while it is unused and unexpired and the run keeps its product, point, parcel, payment terms and origin; otherwise it quotes afresh. Poll GET /ship-jobs/{jobId} or subscribe to order.shipped / order.failed. BUSINESS_WALLET also needs wallet.spend.
Request
Headers
| Name | In | Type | Description |
|---|---|---|---|
AuthorizationRequired | header | string | Bearer <API key> |
Idempotency-KeyRequired | header | string | 8–100 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,100}$ |
Path parameters
| Name | In | Type | Description |
|---|---|---|---|
orderIdRequired | path | string | Pattern ^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$ |
Body ShipRequest
| Field | Type | Description |
|---|---|---|
paymentModeRequired | enum | BUSINESS_WALLET also needs the wallet.spend scope.One of PREPAID, PAY_ON_PICKUP, BUSINESS_INVOICE, BUSINESS_WALLET |
originPointCodeOptional | string | Relay drop-off point; defaults to the store's usual point. |
originAddressTextOptional | string | Express pickup address; defaults to the store's. |
pickupAtOptional | string (date-time) | |
prohibitedItemsDeclarationRequired | Declaration |
Response
| Status | Meaning |
|---|---|
200 | Replay |
202 | Queued |
The body is { "status": "success", "data": … }. Fields of data (ShipJobResult):
| Field | Type | Description |
|---|---|---|
jobRequired | ShipJob | |
replayedRequired | 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. |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |