Skip to main content
Sendcloud’s Ship-an-Order API is a one-stop shop for creating labels for your orders. Shipping is a complex interaction that includes various elements of an order: its weight, the preferred carrier, the destination country, and insurance. Sendcloud’s Ship-an-Order API easily automates this process. The Ship-an-Order API has two endpoints:
  1. Request a label for one or more orders asynchronously: creates labels for a single or multiple orders. The response contains parcel IDs that can be used to retrieve the actual label(s).
  2. Request a label for a single order synchronously: creates a label for a single order and returns the label in the response.
Using this API, you can:
  • Ship one or multiple existing orders in the Sendcloud system in a single API call.
  • Ship to addresses and service points.
  • Use Sendcloud features like shipping rules, shipping defaults, etc.
  • Add brand information to labels and tracking emails.
This guide walks you through the functions of each field in the API.

​
Before you begin

Make sure you complete the following steps before you start working with the Ship-an-Order API:
1

Have an order ready

Create an order using the Create/update orders in batch endpoint of the Orders v3 API. You can also use the Retrieve a list of orders endpoint to list all existing orders created via different sources, e.g. the API or plug-and-play integrations (Shopify, eBay, etc).When using the Ship-an-Order API to ship plug-and-play integrations’ orders, any parcel and tracking updates (or “Feedback”) will be automatically sent back to the source of the order (Shopify, eBay, etc.)
2

Set up shipping defaults

Shipping defaults apply when information such as weight or the shipping method of an order needs to be filled in automatically.If something is missing in the order, your shipping defaults will be used to fill in the information, e.g. default weight, total insurance, preferred shipping method, etc.

Shipping defaults

Read about setting up shipping defaults in our help center
3

Set up shipping rules

Shipping rules work by creating conditions and applying the respective scenarios, for example: If the weight is less than 10kg, ship with PostNL Standard. Once set up, they will apply to all orders that meet the criteria and automatically update these orders with the requested action.For the rule created above, all orders that weigh 10kg or less will have this shipping rule applied to them. The action “ship with PostNL Standard” is the change that applies to orders that meet the condition.

Shipping rules

Learn more about shipping rules in our help center

​
Top-level fields

Both endpoints in the Ship-an-Order API have several top-level fields which apply to all orders in the request.

​
integration_id

The ID of the integration that your orders belong to. Note that:
Use the Retrieve a list of integrations endpoint to get a list of all your integrations

​
orders or order

Contains all the information about your orders, e.g. order_id, order_number, and other fields related to the currency and shipping rules applied
Example request body for the asynchronous endpoint
{
  "integration_id": 12345,
  "orders": [
    {
      "order_id": "ORDER-ID-1"
    },
    {
      "order_number": "ORDER-NUMBER-2"
    }
  ]
}
Example request body for the synchronous endpoint
{
  "integration_id": 12345,
  "order": {
    "order_id": "ORDER-ID-1"
  }
}

​
sender_address_id

Sets the “from” address when creating a label.
  • If sender_address_id is provided in the request, it will not automatically override a corresponding shipping rule to use a different sender address in the following cases:
    • apply_shipping_rules is set to true for an order.
    • A shipping rule exists and is active
  • Each address has an id which can be used as a value in this field. If not provided, the endpoints will automatically use the default sender address set up in the panel.
  • Although a sender address contains brand information, the endpoints will not automatically use this information. To use branding on the labels and tracking emails, use the field brand_id.
Use the Retrieve a list of sender addresses endpoint to get a list of your sender addresses.
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"
    }
  ]
}
Example request body for the synchronous endpoint
{
  "integration_id": 12345,
  "sender_address_id": 17,
  "order": {
    "order_id": "ORDER-ID-1"
  }
}

Sender addresses

Read more in-depth documentation on sender addresses

​
brand_id

This field sets the brand ID to create tracking emails and links with the correct branding.
  • The Retrieve a list of brands endpoint returns all the brands created in your Sendcloud account.
  • If no brand_id is provided, the created labels and tracking emails will be unbranded.
Example request body for the asynchronous endpoint
{
  "integration_id": 12345,
  "brand_id": 42,
  "orders": [
    {
      "order_id": "ORDER-ID-1"
    },
    {
      "order_number": "ORDER-NUMBER-2"
    }
  ]
}
Example request body for the synchronous endpoint
{
  "integration_id": 12345,
  "brand_id": 42,
  "order": {
    "order_id": "ORDER-ID-1"
  }
}

Brands

Learn how to set up and manage your brands in our help center

​
label (synchronous endpoint only)

For the Request a label for a single order synchronously endpoint only, the label field is used to define the format of the label you want to create.
  • The mime_type field lets you specify the format of the label file.
  • The dpi field lets you specify the file resolution.
Additional information about the mime_type and dpi fields can be found in the endpoint’s API reference.
Example request body for the synchronous endpoint
{
  "integration_id": 12345,
  "label": {
    "mime_type": "application/pdf",
    "dpi": 72
  },
  "order": {
    "order_id": "ORDER-ID-1"
  }
}

​
ship_with

The ship_with object is used to define how you would like to ship your order. The object consists of two fields: shipping_option_code and contract_id.

​
shipping_option_code

A unique identifier that displays what carrier and what set of shipping functionalities you want to use.
Use the Create a list of shipping options endpoint to get a list of available shipping option codes.
This field interacts with shipping rules in the following ways:
  • If a shipping rule that controls the shipping method exists and is active, and the apply_shipping_rules field is true for an order, that shipping rule will override the value in shipping_option_code to create the label.
  • When apply_shipping_rules is false, the value in shipping_option_code is used.
If this field is not provided, the shipping_method defined in the order will be used to create the label. The shipping_method field defines the chosen shipping method. Note that the order could already have this property. A shipping_method can be assigned to an order in the following ways, in order of priority:
  • Via the Sendcloud panel.
  • Via the shipping rules created on the account.
  • By the applied shipping defaults.
  • Based on the carriers enabled on the account and considering filters like dimension, weight, origin and destination country, postal code, etc.
  • And if no carriers are enabled on the account, the Unstamped Letter shipping method will be applied to the order.

​
contract_id

The ID of a contract with any carrier.
  • When a contract_id is included in the request, the Ship-an-Order API will use this contract.
  • When a contract_id is not included, if you have a direct contract with the carrier, that will be used.
  • Otherwise, Sendcloud’s rates for the carrier will be used.
Use the Retrieve a list of contracts endpoint to get a list of your contracts.
Example request body for the asynchronous endpoint
{
  "integration_id": 12345,
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "contract_id": 517,
      "shipping_option_code": "postnl:standard"
    }
  },
  "orders": [
    {
      "order_id": "ORDER-ID-1"
    },
    {
      "order_number": "ORDER-NUMBER-2"
    }
  ]
}
Example request body for the synchronous endpoint
{
  "integration_id": 12345,
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "contract_id": 517,
      "shipping_option_code": "postnl:standard"
    }
  },
  "order": {
    "order_id": "ORDER-ID-1"
  }
}

​
Order-level fields

This fields are all part of an order object within the orders array (as used in the asynchronous endpoint) or within the single order object (as used in the synchronous endpoint).
Use the Retrieve an order or Retrieve a list of orders endpoints to get information about one or multiple orders.

​
order_id and order_number

One or both of these fields must be provided to identify the order you want to ship.

​
order_id

An external order ID assigned by the shop system to the order.
  • If order_number is not provided, the order_id is required in the order object, and an order that matches the order_id and the top-level integration_id must exist in the Sendcloud system.
  • If order_number is provided, order_id is not necessary.
  • If both order_id and order_number are provided, an order matching the order_id, order_number, and the top-level integration_id must exist in the system.
Example order object with both fields
{
  "order_id": "ORDER-ID-1",
  "order_number": "ORDER-NUMBER-1"
}
Example order object with only the order_id field
{
  "order_id": "ORDER-ID-1"
}

​
order_number

A unique order number generated manually or by the shop system.
  • If order_id is not provided, the order_number is required in the order object, and an order that matches the order_number and the top-level integration_id must exist in the Sendcloud system.
  • If order_id is provided, order_number is not necessary.
  • If both order_id and order_number are provided, an order matching the order_id, order_number, and the top-level integration_id must exist in the system.
Example order object with both fields
{
  "order_id": "ORDER-ID-1",
  "order_number": "ORDER-NUMBER-1"
}
Example order object with only the order_number field
{
  "order_number": "ORDER-NUMBER-1"
}

​
apply_shipping_rules

Controls whether shipping rules set up in the Sendcloud panel will be applied to the order. When apply_shipping_rules is set to true for an order, shipping rules will be applied to that order before creating the label. Note that:
  • Enabling this option overrides the shipping_option_code provided via the ship_with option.
  • Enabling this option also overrides any defaults set by the your applied shipping defaults.
  • By default, apply_shipping_rules is set to false.
Example order object
{
  "order_id": "ORDER-ID-1",
  "apply_shipping_rules": true
}

​
Label retrieval

After successfully creating labels via the Ship-an-Order API, you can retrieve them based on the type of endpoint used.

​
Use the Parcel Documents API if you used the asynchronous endpoint

If you used the Request a label for one or more orders asynchronously endpoint, use the Retrieve a parcel document endpoint to retrieve your label. The response from the asynchronous endpoint contains parcel IDs that can be used to retrieve the label document. In your request to the Parcel Documents API endpoint, use the parcel_id and set the document_type to label. You can specify the dpi in the query parameters, and the Accept header to define the label MIME type.
Request method, URL and headers
GET https://panel.sendcloud.sc/api/v3/parcels/1234567/documents/label?dpi=150
Accept: image/png
Example response
200 OK
Content-Type: image/png
(binary image data)

​
Get the label in the response from the synchronous endpoint

If you used the Request a label for a single order synchronously endpoint, the label file will be included directly in the JSON response, encoded in base64.
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"
  }
}
Example response
{
  "data": [
    {
      "parcel_id": 5810773,
      "order_id": "ORDER-ID-1",
      "label": {
        "file": <base64 encoded file>,
        "mime_type": "application/pdf",
        "dpi": 72
      }
    }
  ]
}

​
Announcement errors

If label creation fails due to carrier-related issues, you can view parcels with error messages in the Action required section of the Sendcloud panel. For synchronous endpoints, any errors will be included in the response.