Skip to main content
Use the Ship an Order API 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:
1

Have an order available in Sendcloud

Orders can be created via the Orders API or through a plug-and-play integration (Shopify, eBay, WooCommerce, etc).
2

Confirm the order is ready for shipping (if needed)

You can use the Retrieve an order endpoint to confirm the order is available.
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.
3

(Optional) Configure Shipping Defaults

Shipping Defaults can automatically fill in missing shipment data (for example weight, insurance, or preferred shipping method).

Shipping defaults

Read about setting up shipping defaults in our help center
4

(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.

Shipping rules

Learn more about shipping rules in our help center
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
EndpointRequest a label for a single order synchronously
Max orders per request1
HTTP status code201
ResponseParcel 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
EndpointRequest a label for one or more orders asynchronously
Max orders per request1–20
HTTP status code202
ResponseParcel references for successful orders + errors array for failed ones
All orders in an asynchronous request must belong to the same integration_id.

​
Request examples

​
Asynchronous request

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

​
Synchronous request

Example request body for the synchronous endpoint
{
  "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
    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.
  • 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 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 (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.
You may need to retrieve supporting values before calling this endpoint:

​
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 endpoint. You can control the output format using:
  • dpi (query parameter)
  • Accept header (MIME type)
Request method, URL and headers
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.
Request method, URL and body
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 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.