Submit shipping request

Creates a shipping request for the given items using a previously returned quote.

POST /api/v1/ship/request

Submit shipping request

cURL

curl --request POST \
  --url https://api.example.com/api/v1/ship/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "<string>"
}
'

200

{
  "order_id": "order_123",
  "status": "success"
}

Creates a shipping request using a quote returned by /api/v1/ship/quote. Once accepted, the items are queued for fulfillment and removed from the user’s available inventory. No further sellback or shipping is possible.

Shipping fees are settled B2B. No payment, signature, or transaction is required from the end user.

Request body

quote_id · string · required

Quote ID from /api/v1/ship/quote (the quotes[].id value).

Example request

POST /api/v1/ship/request
X-API-Key: <your_api_key>
Content-Type: application/json

{
  "quote_id": "quote_01HF8X2YJK9PMQ4ZRT7NVCB6WD_rate_priority"
}

Response: success

200

{
  "order_id": "order_123",
  "status": "success"
}

order_id · string

Order identifier. In sandbox, the format is order_<16-char base64url>.

status · string

Always success on a 2xx response.

Sandbox does not emit the { order_id: null, status: "error", error_message } envelope. All error cases return a 4xx status with { "error": "..." } (see below). The error envelope is reserved for future production behavior.

Errors

Status	Body	Cause
400	{ "error": "quote_id is required" }	quote_id missing, non-string, or malformed (no _rate_ separator).
400	{ "error": "Quote expired" }	The quote session_id is unknown, the quote has expired (15 minutes in sandbox), or the specific rate_<key> was not found in the session.
400	{ "error": "Item already shipped" }	One or more items in the quote session are already locked into another shipping order.
500	{ "error": "Failed to create shipping request" }	Internal error.

Sandbox notes

A successful ship/request in sandbox creates an order with status: "queued" and never advances. tracking_number, tracking_url, shipped_at, and delivered_at remain null for the lifetime of the sandbox process. Production cycles through the full status set (see /api/v1/ship/order/:order_id).

• Shipping fees are billed B2B to the partner on a periodic invoice cycle. No per-request charge is collected from the end user via this API.
• Once a shipping request is created, the included items are locked and cannot be sold back via /api/v1/vm/buyback.
• Tracking numbers and status transitions can be polled via /api/v1/ship/order/:order_id.