> ## Documentation Index
> Fetch the complete documentation index at: https://dev.phygitals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit shipping request

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

Creates a shipping request using a quote returned by [`/api/v1/ship/quote`](/api-reference/shipping/quote). Once accepted, the items are queued for fulfillment and removed from the user's available inventory. No further sellback or shipping is possible.

<Note>
  **Shipping fees are settled B2B.** No payment, signature, or transaction is required from the end user.
</Note>

## Request body

<ParamField body="quote_id" type="string" required>
  Quote ID from [`/api/v1/ship/quote`](/api-reference/shipping/quote) (the `quotes[].id` value).
</ParamField>

## Example request

```http theme={"dark"}
POST /api/v1/ship/request
X-API-Key: <your_api_key>
Content-Type: application/json

{
  "quote_id": "quote_01HF8X2YJK9PMQ4ZRT7NVCB6WD_rate_priority"
}
```

## Response: success

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "order_id": "order_123",
    "status": "success"
  }
  ```
</ResponseExample>

<ResponseField name="order_id" type="string">
  Order identifier. In [sandbox](/enterprise-api/sandbox), the format is `order_<16-char base64url>`.
</ResponseField>

<ResponseField name="status" type="string">
  Always `success` on a 2xx response.
</ResponseField>

<Note>
  **[Sandbox](/enterprise-api/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.
</Note>

## 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](/enterprise-api/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](/enterprise-api/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`](/api-reference/shipping/order)).

<Note>
  * 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`](/api-reference/sellback).
  * Tracking numbers and status transitions can be polled via [`/api/v1/ship/order/:order_id`](/api-reference/shipping/order).
</Note>