Ship an Order

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. All of these elements are utilized by Sendcloud’s Ship-an-Order API to automate this process.

The Ship-an-Order API has two endpoints:

Async create labels (batch): creates labels for a single or multiple orders. The response contains parcel IDs that can be used to retrieve the actual label(s).
Sync create label: 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 utilities 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

Create an order

Create an order using the Orders V3 API. This endpoint returns all existing orders created via different sources like Orders V3 Create endpoint, plug-and-play integrations, for example — 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.)

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. Learn more about the Shipping Defaults.

If something is missing in the order, the Shipping Default set will be used to fill in the information, for example — default weight, total insurance, preferred shipping method, etc.

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.

Learn more about how to use Shipping Rules.

Async Create Labels request fields’ usage

Global level fields

Global-level fields apply their data to all orders in the request. Those are the integration_id, orders, sender_address_id, brand_id, and ship_with.

integration_id

Contains the ID of the integration, each order is provided with this ID. Note the following:

You cannot provide orders belonging to different integrations in the same request, all orders must belong to the same integration.
You can retrieve the integration_id of a specific order by using the GET Orders V3 API endpoint.
You can also use the Integrations V3 API to view the list of all the integrations you own.

orders

Contains all the information that defines the orders you work with, for example — order_id, order_number, and other fields related to the currency and shipping rules applied.

The async create labels endpoint requires at least one order information to create the corresponding labels.
You can use the Orders V3 API to create and retrieve orders.
A further breakdown of each field within this object is explained in the section named Orders level fields below.

Example:

 1{
 2  "integration_id": 12345,
 3  "orders": [
 4    {
 5      "order_id": "ORDER-ID-1"
 6    },
 7    {
 8      "order_number": "ORDER-NUMBER-2"
 9    }
10  ]
11}

sender_address_id

The sender address 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.
The Sender Address API endpoint returns a list of all the sender addresses that have been saved to your Sendcloud account.
Each address has an id which is the address ID that can be used as a value in this field. If not provided, async create labels will automatically use the default sender address set up in the panel. Note that even though sender_address contains brand information, async create labels will not use this information anywhere. To use branding on the labels and tracking emails, use the field brand_id.

For further information, refer to the Sendcloud developer docs.

Example:

 1{
 2  "integration_id": 12345,
 3  "sender_address_id": 17,
 4  "orders": [
 5    {
 6      "order_id": "ORDER-ID-1"
 7    },
 8    {
 9      "order_number": "ORDER-NUMBER-2"
10    }
11  ]
12}

brand_id

This field sets the brand ID to create tracking emails and links with the correct branding.

The Brands API has a list endpoint that lets you view all the brands created in your Sendcloud account.
To create a brand in your account, learn How to set up your brand.
If no brand_id is provided, the created labels and tracking emails will be unbranded.

Example:

 1{
 2  "integration_id": 12345,
 3  "brand_id": 42,
 4  "orders": [
 5    {
 6      "order_id": "ORDER-ID-1"
 7    },
 8    {
 9      "order_number": "ORDER-NUMBER-2"
10    }
11  ]
12}

ship_with

The ship_with object can be 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.
- 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 of shipping_option_code is used.
- When no value for shipping_option_code is provided, shipping_method from the order will be used.
  - The shipping_method field defines the chosen shipping method. Note that the order could already have this property. A shipping_method could be assigned to an order in the following ways in 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.
- Use the Shipping Options endpoint to get a list of available shipping option codes.
The contract_id field defines the ID of a contract with any carrier. Note the following:
- When contract_id is provided in the request, the Ship-an-Order API uses this contract.
- When not provided, if you have a direct contract with a carrier, that will be used.
- Else a transactional (Sendcloud’s) contract will be used.
- Use the Contracts V3 API to get a list of all available contracts.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "orders": [
11    {
12      "order_id": "ORDER-ID-1"
13    },
14    {
15      "order_number": "ORDER-NUMBER-2"
16    }
17  ]
18}

Orders level fields

These fields are set at the orders’ level, the data is applied to a specific order in the request.

order_id

The order_id field contains an external order ID assigned by the shop system to the order. Note the following:

If order_number is not provided, an order_id is required, and the order with the given integration_id and order_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, the order with the given integration_id, order_id, and order_number must exist in the system.

You can retrieve information about an order by using the Orders V3 API.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "orders": [
11    {
12      "order_id": "ORDER-ID-1",
13      "order_number": "ORDER-NUMBER-1"
14    },
15    {
16      "order_id": "ORDER-ID-2"
17    }
18  ]
19}

order_number

The order_number is a unique order number generated manually or by the shop system. Note the following:

If order_id is not provided, an order_number is required, and the order with the given integration_id and order_number must exist in the Sendcloud system. If order_id is provided, order_number is not required.
If both order_id and order_number are provided, the order with the given integration_id, order_id, and order_number must exist in the system.

You can retrieve information about the order by using the Orders V3 API.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "orders": [
11    {
12      "order_id": "ORDER-ID-1",
13      "order_number": "ORDER-NUMBER-1"
14    },
15    {
16      "order_number": "ORDER-NUMBER-2"
17    }
18  ]
19}

apply_shipping_rules

If apply_shipping_rules is set to true, the Shipping Rules set up via the panel will be applied to the order for which apply_shipping_rules is set. Note the following:

Enabling this option overrides the shipping_option_code provided via the ship_with option.
Enabling this option also overrides any defaults set by the applying Shipping Defaults.
By default, apply_shipping_rules is set to false.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "orders": [
11    {
12      "order_id": "ORDER-ID-1",
13      "apply_shipping_rules": true
14    },
15    {
16      "order_number": "ORDER-NUMBER-2"
17    }
18  ]
19}

Sync Create Label request fields’ usage

Global level fields

Global-level fields apply their data to all orders in the request. Those are the integration_id, order, sender_address_id, brand_id, and ship_with.

integration_id

Contains the ID of the integration to which the provided order belongs. Note the following:

You can retrieve the integration_id of a specific order by using the GET Orders V3 API endpoint.
You can also use the Integrations V3 API to view the list of all the integrations you own.

Example:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_id": "ORDER-ID-1"
5  }
6}

order

Contains all the information that defines the order you work with, for example — order_id, order_number, and other fields related to the currency and shipping rules applied.

The sync create label endpoint requires exactly one order information so that a label for that order can be created.
You can use the Orders V3 API to create and retrieve orders.
A further breakdown of each field within this object is explained in the section named Order level fields below.

Example:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_id": "ORDER-ID-1"
5  }
6}

sender_address_id

The sender address 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.
The Sender Address API endpoint returns a list of all the sender addresses that have been saved to your Sendcloud account.
Each address has an id which is the address ID that can be used as a value in this field. If not provided, async create labels will automatically use the default sender address set up in the panel. Note that even though sender_address contains brand information, async create labels will not use this information anywhere. To use branding on the labels and tracking emails, use the field brand_id.

For further information, refer to the Sendcloud developer docs.

Example:

1{
2  "integration_id": 12345,
3  "sender_address_id": 17,
4  "order": {
5    "order_id": "ORDER-ID-1"
6  }
7}

brand_id

This field sets the brand ID to create tracking emails and links with the correct branding.

The Brands API has a list endpoint that lets you view all the brands created in your Sendcloud account.
To create a brand in your account, learn How to set up your brand.
If no brand_id is provided, the created labels and tracking emails will be unbranded.

Example:

1{
2  "integration_id": 12345,
3  "brand_id": 42,
4  "order": {
5    "order_id": "ORDER-ID-1"
6  }
7}

label

You can specify the format of the label using this object.
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 mime_type and dpi fields can be found in the Ship-an-Order API Docs.

Example:

 1{
 2  "integration_id": 12345,
 3  "label": {
 4    "mime_type": "application/pdf",
 5    "dpi": 72
 6  },
 7  "order": {
 8    "order_id": "ORDER-ID-1"
 9  }
10}

ship_with

The ship_with object can be 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.
- 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 of shipping_option_code is used.
- When no value for shipping_option_code is provided, shipping_method from the order will be used.
  - The shipping_method field defines the chosen shipping method. Note that the order could already have this property. A shipping_method could be assigned to an order in the following ways in 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.
- If no carriers are enabled on the account, the Unstamped Letter shipping method will be applied to the order.
- Use the Shipping Options endpoint to get a list of available shipping option codes.
- The contract_id field defines the ID of a contract with any carrier. Note the following:
- When contract_id is provided in the request, the Ship-an-Order API uses this contract.
- When not provided, if you have a direct contract with a carrier, that will be used.
- Else a transactional (Sendcloud’s) contract will be used.
- Use the Contracts V3 API to get a list of all available contracts.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "order": {
11    "order_id": "ORDER-ID-1"
12  }
13}

Order level fields

These fields are set at the “order” level i.e. when set, the data is applied to a specific order in the request.

order_id

The order_id field contains an external order ID assigned by the shop system to the order. Note the following:

If order_number is not provided, an order_id is required, and the order with the given integration_id and order_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, the order with the given integration_id, order_id, and order_number must exist in the system.

You can retrieve information about an order by using the Orders V3 API.

Example #1:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_id": "ORDER-ID-1"
5  }
6}

Example #2:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_id": "ORDER-ID-2",
5    "order_number": "ORDER-NUMBER-2"
6  }
7}

order_number

The order_number is a unique order number generated manually or by the shop system. Note the following:

If order_id is not provided, an order_number is required, and the order with the given integration_id and order_number must exist in the Sendcloud system. If order_id is provided, order_number is not required.
If both order_id and order_number are provided, the order with the given integration_id, order_id, and order_number must exist in the system.

You can retrieve information about the order by using the Orders V3 API.

Example #1:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_number": "ORDER-NUMBER-1"
5  }
6}

Example #2:

1{
2  "integration_id": 12345,
3  "order": {
4    "order_id": "ORDER-ID-2",
5    "order_number": "ORDER-NUMBER-2"
6  }
7}

apply_shipping_rules

If apply_shipping_rules is set to true, the Shipping Rules set up via the panel will be applied to the order. Note the following:

Enabling this option overrides the shipping_option_code provided via the ship_with option.
Enabling this option also overrides any defaults set by the applying Shipping Defaults.
By default, apply_shipping_rules is set to false.

Example:

 1{
 2  "integration_id": 12345,
 3  "ship_with": {
 4    "type": "shipping_option_code",
 5    "properties": {
 6      "contract_id": 517,
 7      "shipping_option_code": "postnl:standard"
 8    }
 9  },
10  "order": {
11    "order_id": "ORDER-ID-1",
12    "apply_shipping_rules": true
13  }
14}

Label Retrieval

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

Asynchronous Label Creation: Use the parcel documents endpoint of the Parcel V3 API.
Synchronous Label Creation: Retrieve the label file directly in the API response.

Parcel Documents API

When a label is created through the Ship-an-Order API, the response includes a parcel ID. This ID can be used with the Parcel V3 API to retrieve the label document. You’ll need to specify the document type and parcel ID, and you can customize options such as DPI and document mime type through HTTP headers.

Example Request:

1GET https://panel.sendcloud.sc/api/v3/parcels/5810773/documents/label?dpi=72
2Accept: image/png

Expected Response:

1200 OK
2<binary file>

Retrieving a Label in the Response

For synchronous endpoints, the label file will be included directly in the JSON response, encoded in base64.

Example Request:

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:

 1{
 2  "data": [
 3    {
 4      "parcel_id": 5810773,
 5      "order_id": "ORDER-ID-1",
 6      "label": {
 7        "file": <base64 encoded file>,
 8        "mime_type": "application/pdf",
 9        "dpi": 72
10      }
11    }
12  ]
13}

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 Shipping. For synchronous endpoints, any errors will be included in the response.

Developers Documentation

Ship an Order

Before you begin

Create an order

Set up Shipping Defaults

Set up Shipping Rules

Async Create Labels request fields’ usage

Global level fields

integration_id

orders

sender_address_id

brand_id

ship_with

Orders level fields

order_id

order_number

apply_shipping_rules

Sync Create Label request fields’ usage

Global level fields

integration_id

order

sender_address_id

brand_id

label

ship_with

Order level fields

order_id

order_number

apply_shipping_rules

Label Retrieval

Parcel Documents API

Retrieving a Label in the Response

Announcement Errors

On this page