Create a parcel

Sendcloud’s flexible shipping API covers every part of the shipping process—from label creation right up to the point of delivery. Ready to put your shipping processes on autopilot? Read on to learn how to create your first parcel with Sendcloud’s shipping API.

There are two ways to create via the API:

Method 1: Create a parcel object

  • This is the most flexible means of creating a parcel. The parcel object is created in the Sendcloud system, but the parcel is not immediately announced with the carrier.
  • This gives you time to continue making changes to the parcel data and decide on a shipping method right up until the moment you’re ready to create the label.
  • Parcels can be processed either via the Sendcloud panel, or you can perform all interactions via the API, depending on your specific use case.

Method 2: (Advanced option): Create the parcel and shipping label in a single API call

  • This method is described in more detail at the end of this tutorial.

To help get you started, this guide will cover the basics of creating a parcel via the API, step-by-step.

Once the parcel is created, you can continue on to the next steps to learn how to choose a shipping method and print the label.


Before you begin:

  1. Make sure you’ve completed basic account set up. See Getting started with Sendcloud
  2. You’ll need to have obtained your API keys so you can authenticate with our API. See Authentication
  3. You’ll need access to a tool that allows you to make API calls. Examples are Postman and Insomnia.

API endpoint

Parcels are created by sending a HTTP POST request to the Create a parcel endpoint: https://panel.sendcloud.sc/api/v2/parcels

Headers

Headers provide context and additional meta-data to the server to help it process requests.

Authorization header

Every time you make an API call, you need to authenticate your connection to Sendcloud by including your API keys through a HTTP header.


Step 1: Prepare your request

In the body of your HTTP request, you need to specify all the required information for the shipping label. Below you can find an example which will create a parcel object in your Sendcloud account.

Example request

 1{
 2
 3    "parcel":
 4    {
 5        "name": "John Doe",
 6        "company_name": "FlowerShop",
 7        "email": "john@doe.com",
 8        "telephone": "+31611223344",
 9        "address": "Fürstenrieder Str.",
10        "house_number": "70",
11        "address_2": "",
12        "city": "Munich",
13        "country": "DE",
14        "postal_code": "80686",
15        "country_state": null,
16        "to_service_point": 10168633,
17        "to_post_number": 262373726,
18        "customs_invoice_nr": "",
19        "customs_shipment_type": null,
20        "parcel_items":
21        [
22            {
23                "description": "T-Shirt",
24                "hs_code": "6109",
25                "origin_country": "SE",
26                "product_id": "898678671",
27                "properties":
28                {
29                    "color": "Blue",
30                    "size": "Medium"
31                },
32                "quantity": 2,
33                "sku": "TST-OD2019-B620",
34                "value": "19.95",
35                "weight": "0.9"
36            },
37            {
38                "description": "Laptop",
39                "hs_code": "84713010",
40                "origin_country": "DE",
41                "product_id": "5756464758",
42                "properties":
43                {
44                    "color": "Black",
45                    "internal_storage": "2TB"
46                },
47                "quantity": 1,
48                "sku": "LT-PN2020-B23",
49                "value": "876.97",
50                "weight": "1.69"
51            }
52        ],
53        "weight": "3.49",
54        "length": "31.5",
55        "width": "27.2",
56        "height": "12.7",
57        "total_order_value": "896.92",
58        "total_order_value_currency": "EUR",
59        "shipment":
60        {
61            "id": 1316,
62            "name": "DHL Parcel Connect 2-5kg to ParcelShop"
63        },
64        "shipping_method_checkout_name": "Battery WarehouseX DHL",
65        "sender_address": 1,
66        "quantity": 1,
67        "total_insured_value": 0,
68        "is_return": false,
69        "request_label": false,
70        "apply_shipping_rules": false,
71        "request_label_async": false
72    }
73}
The important thing to note here is that the request_label parameter is set to false. This allows you to create a parcel without announcing it to a carrier or creating a shipping label. The parcel will be created using the default shipping method you saved in your account, and can be updated later.

Parcel fields

There are many other additional fields, that you can specify when creating a parcel. An example would be the sender_address parameter which lets you ship a parcel from a different sender location, or the parameters related to customs information for international shipping.

You can find a list of the supported fields in our API reference.


Step 2: Send your request

Take the example above, and use it to make a POST request to http://panel.sendcloud.sc/api/v2/parcels.

 1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v2/parcels' \
 2--header 'Authorization: Basic <credentials>' \
 3--data-raw '
 4{
 5    "parcel":
 6    {
 7        "name": "John Doe",
 8        "company_name": "FlowerShop",
 9        "email": "john@doe.com",
10        "telephone": "+31611223344",
11        "address": "Fürstenrieder Str.",
12        "house_number": "70",
13        "address_2": "",
14        "city": "Munich",
15        "country": "DE",
16        "postal_code": "80686",
17        "country_state": null,
18        "customs_invoice_nr": "",
19        "customs_shipment_type": null,
20        "parcel_items":
21        [
22            {
23                "description": "T-Shirt",
24                "hs_code": "6109",
25                "origin_country": "SE",
26                "product_id": "898678671",
27                "properties":
28                {
29                    "color": "Blue",
30                    "size": "Medium"
31                },
32                "quantity": 2,
33                "sku": "TST-OD2019-B620",
34                "value": "19.95",
35                "weight": "0.9"
36            },
37            {
38                "description": "Laptop",
39                "hs_code": "84713010",
40                "origin_country": "DE",
41                "product_id": "5756464758",
42                "properties":
43                {
44                    "color": "Black",
45                    "internal_storage": "2TB"
46                },
47                "quantity": 1,
48                "sku": "LT-PN2020-B23",
49                "value": "876.97",
50                "weight": "1.69"
51            }
52        ],
53        "weight": "3.49",
54        "length": "31.5",
55        "width": "27.2",
56        "height": "12.7",
57        "total_order_value": "896.92",
58        "total_order_value_currency": "EUR",
59        "shipment":
60        {
61            "id": 1316,
62            "name": "DHL Parcel Connect 2-5kg to ParcelShop"
63        },
64        "shipping_method_checkout_name": "Battery WarehouseX DHL",
65        "sender_address": 253456,
66        "quantity": 1,
67        "total_insured_value": 0,
68        "is_return": false,
69        "request_label": false,
70        "apply_shipping_rules": false,
71        "request_label_async": false
72    }
73}'

If everything went well, you’ll receive a HTTP 200 status code and a response back that looks something like the example below.

Example response

  1{
  2    "parcel":
  3    {
  4        "id": 1,
  5        "address": "Fürstenrieder Str. 70",
  6        "address_2": "",
  7        "address_divided":
  8        {
  9            "street": "Fürstenrieder Str.",
 10            "house_number": "70"
 11        },
 12        "city": "Munich",
 13        "company_name": "FlowerShop",
 14        "country":
 15        {
 16            "iso_2": "DE",
 17            "iso_3": "DEU",
 18            "name": "Germany"
 19        },
 20        "data":
 21        {},
 22        "date_created": "29-06-2022 12:09:24",
 23        "date_announced": null,
 24        "date_updated": "29-06-2022 12:09:24",
 25        "email": "john@doe.com",
 26        "name": "John Doe",
 27        "postal_code": "80686",
 28        "reference": "0",
 29        "shipment":
 30        {
 31            "id": 1316,
 32            "name": "DHL Parcel Connect 2-5kg to ParcelShop"
 33        },
 34        "status":
 35        {
 36            "id": 999,
 37            "message": "No label"
 38        },
 39        "to_service_point": null,
 40        "telephone": "+31611223344",
 41        "tracking_number": "",
 42        "weight": "3.490",
 43        "label":
 44        {},
 45        "customs_declaration":
 46        {},
 47        "order_number": "",
 48        "insured_value": 0,
 49        "total_insured_value": 0,
 50        "to_state": null,
 51        "customs_invoice_nr": "",
 52        "customs_shipment_type": null,
 53        "parcel_items":
 54        [
 55            {
 56                "description": "T-Shirt",
 57                "quantity": 2,
 58                "weight": "0.900",
 59                "value": "19.95",
 60                "hs_code": "6109",
 61                "origin_country": "SE",
 62                "product_id": "898678671",
 63                "properties":
 64                {
 65                    "size": "Medium",
 66                    "color": "Blue"
 67                },
 68                "sku": "TST-OD2019-B620",
 69                "return_reason": null,
 70                "return_message": null
 71            },
 72            {
 73                "description": "Laptop",
 74                "quantity": 1,
 75                "weight": "1.690",
 76                "value": "876.97",
 77                "hs_code": "84713010",
 78                "origin_country": "DE",
 79                "product_id": "5756464758",
 80                "properties":
 81                {
 82                    "color": "Black",
 83                    "internal_storage": "2TB"
 84                },
 85                "sku": "LT-PN2020-B23",
 86                "return_reason": null,
 87                "return_message": null
 88            }
 89        ],
 90        "documents":
 91        [],
 92        "type": null,
 93        "shipment_uuid": "103c1c17-d4f9-413a-b81d-e0274e215747",
 94        "shipping_method": 1316,
 95        "external_order_id": "191148456",
 96        "external_shipment_id": "",
 97        "external_reference": null,
 98        "is_return": false,
 99        "note": "",
100        "to_post_number": "",
101        "total_order_value": "896.92",
102        "total_order_value_currency": "EUR",
103        "quantity": 1,
104        "colli_uuid": "60c05695-fc7d-4731-abbd-9fcc96e4c120",
105        "collo_nr": 0,
106        "collo_count": 1,
107        "awb_tracking_number": null,
108        "box_number": null,
109        "length": "31.50",
110        "width": "27.20",
111        "height": "12.70",
112        "shipping_method_checkout_name": "Battery WarehouseX DHL",
113        "carrier":
114        {
115            "code": "dhl"
116        }
117    }
118}

Some things to note about the response

  • You can see that the newly created parcel has been assigned a parcel "id": 189169249". This is the unique parcel identifier which we will use whenever we want to update a parcel or create the label via the API.
  • The current status of the newly created parcel is "No label". It will appear in the Sendcloud panel under the incoming order overview with the message Ready to process until we create a label for it.

Step 3: Create the shipping label

To create shipping labels via the API, you need to make a PUT request to the Update a parcel endpoint and update the value of request_label to true.

Via this endpoint, you can also make changes to any of the properties that can be used for creating a parcel. See Create a parcel for a list of properties which can be changed.

Generating a label for an existing parcel

In this example, we will update parcel "id": 1" as follows:

  • Create the shipping label by providing the argument "request_label": "true"
  • Change the name of the recipient to a new value
  • Change the shipping method by providing the corresponding id. In this example, we’ll be using the method “Unstamped letter” to create a test label.
Tip: You’ll be invoiced for any shipping labels you create if you don’t cancel or delete them within the cancellation deadline. You can create test labels without receiving a charge by using the shipping method Unstamped letter ("id": "8")
 1curl --location -g --request PUT 'https://panel.sendcloud.sc/api/v2/parcels' \
 2--header 'Authorization: Basic <credentials>' \
 3--data-raw '
 4{
 5    "parcel":
 6    {
 7        "id": 1,
 8        "request_label": true,
 9        "name": "Mr Test",
10        "shipment":
11        {
12            "id": 8,
13            "name": "unstamped letter"
14        }
15    }
16}'

Once you’ve prepared the response body, make a PUT request to the Update a parcel endpoint. Make sure to include your authentication and content headers, as you did in Step 2.

If everything goes well, you should receive a response similar to the one below:

Example response

  1{
  2    "parcel":
  3    {
  4        "id": 1,
  5        "address": "Fürstenrieder Str. 70",
  6        "address_2": "",
  7        "address_divided":
  8        {
  9            "street": "Fürstenrieder Str.",
 10            "house_number": "70"
 11        },
 12        "city": "Munich",
 13        "company_name": "FlowerShop",
 14        "country":
 15        {
 16            "iso_2": "DE",
 17            "iso_3": "DEU",
 18            "name": "Germany"
 19        },
 20        "data":
 21        {},
 22        "date_created": "29-06-2022 12:09:24",
 23        "date_announced": "29-06-2022 12:10:20",
 24        "date_updated": "29-06-2022 12:10:20",
 25        "email": "john@doe.com",
 26        "name": "Mr Test",
 27        "postal_code": "80686",
 28        "reference": "0",
 29        "shipment":
 30        {
 31            "id": 8,
 32            "name": "Unstamped letter"
 33        },
 34        "status":
 35        {
 36            "id": 1000,
 37            "message": "Ready to send"
 38        },
 39        "to_service_point": null,
 40        "telephone": "+31611223344",
 41        "tracking_number": "SCCWF3B9VPDV",
 42        "weight": "3.490",
 43        "label":
 44        {
 45            "normal_printer":
 46            [
 47                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0",
 48                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=1",
 49                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=2",
 50                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=3"
 51            ],
 52            "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/1"
 53        },
 54        "customs_declaration":
 55        {},
 56        "order_number": "",
 57        "insured_value": 0,
 58        "total_insured_value": 0,
 59        "to_state": null,
 60        "customs_invoice_nr": "",
 61        "customs_shipment_type": null,
 62        "parcel_items":
 63        [
 64            {
 65                "description": "T-Shirt",
 66                "quantity": 2,
 67                "weight": "0.900",
 68                "value": "19.95",
 69                "hs_code": "6109",
 70                "origin_country": "SE",
 71                "product_id": "898678671",
 72                "properties":
 73                {
 74                    "size": "Medium",
 75                    "color": "Blue"
 76                },
 77                "sku": "TST-OD2019-B620",
 78                "return_reason": null,
 79                "return_message": null
 80            },
 81            {
 82                "description": "Laptop",
 83                "quantity": 1,
 84                "weight": "1.690",
 85                "value": "876.97",
 86                "hs_code": "84713010",
 87                "origin_country": "DE",
 88                "product_id": "5756464758",
 89                "properties":
 90                {
 91                    "color": "Black",
 92                    "internal_storage": "2TB"
 93                },
 94                "sku": "LT-PN2020-B23",
 95                "return_reason": null,
 96                "return_message": null
 97            }
 98        ],
 99        "documents":
100        [
101            {
102                "type": "label",
103                "size": "a6",
104                "link": "https://panel.sendcloud.sc/api/v2/parcels/191148456/documents/label"
105            }
106        ],
107        "type": "letter",
108        "shipment_uuid": "103c1c17-d4f9-413a-b81d-e0274e215747",
109        "shipping_method": 8,
110        "external_order_id": "191148456",
111        "external_shipment_id": "",
112        "external_reference": null,
113        "note": "",
114        "to_post_number": "",
115        "total_order_value": "896.92",
116        "total_order_value_currency": "EUR",
117        "colli_uuid": "60c05695-fc7d-4731-abbd-9fcc96e4c120",
118        "collo_nr": 0,
119        "collo_count": 1,
120        "awb_tracking_number": null,
121        "box_number": null,
122        "length": "31.50",
123        "width": "27.20",
124        "height": "12.70",
125        "shipping_method_checkout_name": "Battery WarehouseX DHL",
126        "carrier":
127        {
128            "code": "sendcloud"
129        },
130        "tracking_url": "https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=sendcloud&code=SCCWF3B9VPDV&destination=DE&lang=en-us&source=NL&type=letter&verification=80686&servicepoint_verification=&created_at=2022-06-29",
131        "is_return": false
132    }
133}

Notice that the response reflects the updates you have made to the customer name, and that the parcel status is now “Ready to send”. The shipping method has been updated to “Unstamped letter”.


Step 4: Download the shipping label

At the end of the previous step, you should have received a response which contains some URL’s under label. These URL’s are your links to download the shipping label. Labels can be downloaded in PDF format and are provided in A4 size for normal printers, and A6 size for label printers.

Under normal_printer, the start_from value indicates the position of the label on an A4 size page:

  • 0= Top left
  • 1 = Top right
  • 2 = Bottom left
  • 3 = Bottom right

You’ll need to provide your API credentials again to access the link to download your labels. You can do this by making a GET request to the URL of the label you want to access, and including your authentication headers.

GET https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0

Tip: Labels can also be downloaded in bulk directly from the Sendcloud panel under the Created labels tab, or via the Get a PDF label and Bulk PDF label printing endpoints.
Congrats! You just created your first parcel and downloaded the shipping label via the API.

Next steps

You can continue viewing more tutorials or dive directly into exploring our APIs via our API reference.

  • Choose a shipping method - learn how to retrieve the full list of shipping services available to you via Sendcloud
  • Track a parcel - to see how you can track the delivery journey of your newly created parcel as it travels to your customer
  • Create a return - view how you can create a return parcel shipment via the Sendcloud Returns API
  • API references - if you’re an advanced user, browse our API Reference to explore more options for creating parcels and managing your shipping processes.

Advanced options

Create a parcel and immediately request a label in a single API call

If you already know which shipping method you want to use to send your parcel, you can bypass Step 3 above by making a POST request to the Create a parcel endpoint and flag "request_label": "true".

When directly announcing parcels in this way, the shipment field is mandatory, and a shipping method id and name must be provided in the API request. If you’re shipping parcels internationally, pay attention to the additional fields which become mandatory for customs documentations purposes. A full list of required parameters can be found in our API repository

Create a return parcel

You can use the Create a parcel endpoint to create return labels via the API. The process for creating a return label via this method is the same as for creating a parcel, but you must set the value of the is_return property to true and specify the customer’s address address in the from_* fields.

It’s important to note that standard shipping methods don’t apply to return parcels. You can find an overview of available return methods via the List of all shipping methods endpoint and include the parameter is_return: true.

You can also create returns via our Returns API by following the Create a return guide.

Ship parcels and retrieve methods for your sender addresses based in other countries

You can set up multiple sender addresses in your Sendcloud account, and specify which sender address you want to ship from when you Create a parcel. See our documentation on Sender addresses for more info.

Automatically apply your preferred shipping methods via shipping rules

Shipping rules are a Sendcloud feature which can be used in conjunction with the API to take the legwork out of manually choosing and selecting the best method for your created parcels. See our Shipping rules documentation for more details.

You can customize a brand in your Sendcloud account to make use of handy marketing tools, such as customizable tracking notifications and branded return portals for each of your integrations. See more about creating your brand on our Help Center.

Receive real time parcel status updates via Webhooks

Actively receive updates regarding parcel events directly to your application by configuring Webhooks.

Go to top