Developers
API referenceBusiness sign in

Orders

Ship several orders

POST/ship-jobs

Scope orders.shipLIVE keys onlyIdempotency-Key required

1–100 orders in one run; up to 5 runs in progress per Business (429 beyond). Already shipped, cancelled, queued or TEST orders are skipped with a reason.

Request

Headers

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

Body ShipJobsRequest

Request body
FieldTypeDescription
orderIdsRequiredarray of string1–100 items
paymentModeRequiredenumBUSINESS_WALLET also needs the wallet.spend scope.One of PREPAID, PAY_ON_PICKUP, BUSINESS_INVOICE, BUSINESS_WALLET
originPointCodeOptionalstringRelay drop-off point; defaults to the store's usual point.
originAddressTextOptionalstringExpress pickup address; defaults to the store's.
pickupAtOptionalstring (date-time)
prohibitedItemsDeclarationRequiredDeclaration

Response

Success responses
StatusMeaning
200Replay
202Queued

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

Response data
FieldTypeDescription
jobRequiredShipJob
replayedRequiredboolean

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).
404Not 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.
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.
429Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key.