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

# Ship an order

Use the [Ship an Order API](/api/v3/ship-an-order) to generate a shipping label for an order that already exists in Sendcloud.

This is the fastest way to go from an Incoming Order to a label without building a full Shipments API flow.

Ship an Order supports two flows:

* **Synchronous**: Ship **one** order and receive the label file in the response. Best suited for one-off shipments or low volume.
* **Asynchronous**: Ship **one or multiple** orders in a single request. Recommended for batch processing. The response returns parcel references and any per-order errors. Labels are retrieved separately.

Ship an Order supports:

* Shipping to addresses and service points
* Applying Shipping Rules and Shipping Defaults
* Adding brand information to labels and tracking emails

## Before you begin

Before calling the [Ship an Order API](/api/v3/ship-an-order):

<Steps>
  <Step title="Have an order available in Sendcloud">
    Orders can be created via the [Orders API](/api/v3/orders) or through a plug-and-play integration (Shopify, eBay, WooCommerce, etc).
  </Step>

  <Step title="Confirm the order is ready for shipping (if needed)">
    You can use the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint to confirm the order is available.

    <Note>
      Orders are saved asynchronously. If you create an order and immediately request a label, it may not yet be available. If you receive an “order not found” error, retrieve the order first and retry.
    </Note>
  </Step>

  <Step title="(Optional) Configure Shipping Defaults">
    Shipping Defaults can automatically fill in missing shipment data (for example weight, insurance, or preferred shipping method).

    <Card title="Shipping defaults" icon="circle-question" href="https://support.sendcloud.com/hc/en-us/articles/12213808740116-How-to-set-up-your-default-shipping-settings" horizontal>
      Read about setting up shipping defaults in our help center
    </Card>
  </Step>

  <Step title="(Optional) Configure Shipping Rules">
    Shipping Rules allow you to automatically determine how an order should be shipped based on conditions.\
    To apply them during label creation, set `apply_shipping_rules: true` in your request.

    <Card title="Shipping rules" icon="circle-question" href="https://support.sendcloud.com/hc/en-us/articles/10274644599316-Shipping-rules-overview-and-application" horizontal>
      Learn more about shipping rules in our help center
    </Card>
  </Step>
</Steps>

When shipping orders from plug-and-play integrations (e.g. Shopify, eBay, WooCommerce), tracking updates are automatically synced back to the source platform.

## Request a label for a single order synchronously

Use the synchronous endpoint when you need the label returned immediately in the response.

| Key details                |                                                                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**               | [Request a label for a single order synchronously](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) |
| **Max orders per request** | **1**                                                                                                                      |
| **HTTP status code**       | **201**                                                                                                                    |
| **Response**               | Parcel reference + Base64-encoded label file                                                                               |

## Request labels for one or more orders asynchronously

Use the asynchronous endpoint for batch shipping. This endpoint fails gracefully — one order failing does not block others.

| Key details                |                                                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Endpoint**               | [Request a label for one or more orders asynchronously](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) |
| **Max orders per request** | **1–20**                                                                                                                             |
| **HTTP status code**       | **202**                                                                                                                              |
| **Response**               | Parcel references for successful orders + `errors` array for failed ones                                                             |

<Note>All orders in an asynchronous request must belong to the same `integration_id`.</Note>

## Request examples

### Asynchronous request

```json Example request body for the asynchronous endpoint theme={null}
{
  "integration_id": 12345,
  "sender_address_id": 17,
  "orders": [
    {
      "order_id": "ORDER-ID-1"
    },
    {
      "order_number": "ORDER-NUMBER-2"
    }
  ]
}
```

### Synchronous request

```json Example request body for the synchronous endpoint theme={null}
{
  "integration_id": 12345,
  "order": {
    "order_id": "ORDER-ID-1"
  }
}
```

## Common fields you may include

Depending on your flow, your request may include:

### Required fields

* `integration_id` (**required**)
* `order` (**required**, synchronous only)
* `orders` (**required**, asynchronous only; 1–20 orders)
* `order_id` or `order_number` (**at least one required** per order): If both are provided, they must reference the same order under the specified `integration_id`.

### Optional fields

* `ship_with`: explicitly set `shipping_option_code` and optional `contract_id`
* `sender_address_id`: override default sender address
* `brand_id`: apply branding to labels and tracking emails
  <Note>
    The Brands API is currently only available in API v2. This reference will be updated when a v3 version becomes
    available. If you are curious to learn more about setting up and managing brands see this [Help Center
    article](https://support.sendcloud.com/hc/en-us/articles/360041212392-How-to-set-up-your-brand).
  </Note>
* `apply_shipping_rules` (per order): apply Shipping Rules before label creation
* `label_details` (synchronous only): control label format (mime type, DPI)

See the [API reference](/api/v3/ship-an-order) for the complete request schema and all supported fields.

### Shipping method resolution priority

When creating the label, Sendcloud determines the shipping method in the following order:

1. Shipping Rules (if `apply_shipping_rules` = true)
2. `ship_with.shipping_option_code`
3. Existing `shipping_method` on the order
4. Shipping Defaults
5. Fallback to [Unstamped Letter](https://support.sendcloud.com/hc/en-us/articles/210931986-What-is-the-shipping-method-Unstamped-letter) (if no carriers are enabled)

### Contract selection

* If `contract_id` is provided, that contract is used.
* If omitted, Sendcloud uses your direct carrier contract (if available).
* Otherwise, Sendcloud rates are applied.

### Finding related IDs and codes

You may need to retrieve supporting values before calling this endpoint:

* Use the [Retrieve a list of integrations](/api/v3/integrations/retrieve-a-list-of-integrations) endpoint to get a list of all your integrations.
* To find which `shipping_option_code` values are available for a given shipment context, use the **Shipping Options API** (see [Shipping options & quotes](/docs/shipments/shipping-options-and-quotes) endpoint).
  * If you’ve hardcoded shipping method IDs in your system, you can use the **Compat API** to map them to the equivalent `shipping_option_code`.
* Use the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint to get a list of your contracts.
* Use the [Retrieve a list of sender addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint to get a list of your sender addresses.

## Retrieving labels

### If you used the asynchronous endpoint

The async endpoint returns parcel references. Use the Parcel Documents API and to retrieve the label file, make a `GET` request to the [retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint.
You can control the output format using:

* `dpi` (query parameter)
* Accept header (MIME type)

```http Request method, URL and headers theme={null}
GET https://panel.sendcloud.sc/api/v3/parcels/1234567/documents/label?dpi=150
Accept: image/png
```

Supported formats depend on the carrier and configuration (e.g. PDF, PNG, ZPL).

### If you used the synchronous endpoint

The label file is included directly in the JSON response (Base64-encoded). No additional API call is required.

```http Request method, URL and body theme={null}
POST https://panel.sendcloud.sc/api/v3/orders/create-label-sync
{
  "integration_id": 12345,
  "label": {
    "mime_type": "application/pdf",
    "dpi": 72
  },
  "order": {
    "order_id": "ORDER-ID-1"
  }
}
```

The response includes:

* `parcel_id`
* `label.file` (Base64-encoded)
* `label.mime_type`
* `label.dpi`

## Error handling

**Order not found**: If the order was recently created, it may not yet be available.
Retrieve the order first using [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint and retry.

**Partial failures (asynchronous endpoint)**: The asynchronous endpoint may return both successful parcel references and per-order errors in the same response.
Inspect the `errors` array to determine which orders failed and why.

**Carrier or announcement errors**: For synchronous requests, errors are returned directly in the response.
For asynchronous requests, inspect the response and relevant parcel in the Sendcloud platform if needed.

## Limitations of Ship an Order

Compared to the Shipments API, Ship an Order is more limited and does not (yet) support:

* Synchronous multicollo shipping
* Order splitting
* Setting parcel-specific details such as:
  * Weight or dimensions per parcel
  * Items per parcel
  * Insurance per parcel
  * Label notes or delivery dates per parcel

For advanced shipping scenarios, use the [Shipments API](/api/v3/shipments).