International shipping

Sendcloud enables you to deliver orders from Europe to destinations across the globe, through a large selection of reliable and cost-effective shipping methods.

Customs documents

Customs documents are always required for parcels shipping to destinations outside the EU. In most cases a commercial invoice is required by commercial carriers (e.g. UPS and DHL), however postal carriers (e.g. PostNL and Royal Mail) require a CN22 or CN23 form.

Sendcloud will automatically generate the correct type of documentation for your parcel when you create an international parcel through our API. You just need to include some additional properties in your API call, as listed below.

Tip: You can find extensive guides to help you navigate the various types of documentation required for international shipping, and tips on shipping post-Brexit, on our Help Center.

Required fields

When you Create a parcel for an international shipment, you need to include the properties below in your request. This is to ensure that customs documentation can be correctly rendered, and that the items in your order are listed alongside their value and description, as required.

Parameter Type Required Description
customs_invoice_number string Customs invoice number
customs_shipment_type integer Customs shipment type. Accepted values are: 0 - Gift 1 - Documents, 2 Commercial Goods, 3 Commercal Sample, 4 - Returned Goods
country_state string ✔ (For certain countries) Code of the state (e.g. New York = NY). Required for Australia, Canada, Italy and USA.
parcel_items array (parcel_items) List of items contained in the order. See Parcel items object.

Parcel items object

The following properties should be included in the parcel_items object:

Parameter Type Required Description
description string Description of the product.
quantity integer Number of items shipped.
weight weight (decimal number) Weight of the product in kilograms.
value decimal (2 decimal places) Value of the product.
hs_code string The 8 digit Harmonized System Code
origin_country string ISO-2 country code from where the products were originally produced.
product_id string The internal ID of the product.
properties array (properties) The properties of the product, e.g. colour: Black

Example

 1{
 2    "parcel_items":
 3    [
 4        {
 5            "description": "T-Shirt",
 6            "hs_code": "6109",
 7            "origin_country": "SE",
 8            "product_id": "898678671",
 9            "properties":
10            {
11                "color": "Blue",
12                "size": "Medium"
13            },
14            "quantity": 2,
15            "sku": "TST-OD2019-B620",
16            "value": "19.95",
17            "weight": "0.9"
18        }
19    ]
20}

Tip: Adding items to commercial invoices & CN22/23 customs forms

The amount of items you can include on a single commercial invoice differs depending on the type of shipping carrier you have selected. For a full overview, see our Help Center.


Tax identifiers

You can include your tax identifiers in your request when you create a parcel. This helps to ensure your parcel complies with post-Brexit shipping requirements when sending items to the United Kingdom. More information about shipping post-Brexit can be found on our Help Center.

Tip: If you have saved your tax identification numbers in your Sendcloud account under Sender addresses, then you don’t need to include these properties in your request. They will automatically be added to your customs documents when you create the parcel, so long as these details are saved to the same sender address as you specify in the sender_address id property.
Parameter Type Required Description
from_vat_number string VAT number of the sender
from_eori_number string EORI number of the sender
from_inbound_vat_number string ✔ for shipments from EU to GB GB VAT number
ffrom_inbound_eori_number string ✔ for shipments from EU to GB GB EORI number
from_ioss_number string IOSS (Import One-Stop Shop) number of the sender

Creating an International shipment

Here’s an example request to Create a parcel once we’ve included the properties listed above:

  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        "id": 1,
  8        "address": "70 Flowers Avenue",
  9        "address_2": "",
 10        "address_divided":
 11        {
 12            "street": "Flowers Avenue",
 13            "house_number": "70"
 14        },
 15        "city": "Bolton",
 16        "company_name": "FlowerShop",
 17        "country":
 18        {
 19            "iso_2": "GB",
 20            "iso_3": "GBR",
 21            "name": "United Kingdom"
 22        },
 23        "data":
 24        {},
 25        "date_created": "23-06-2022 11:38:22",
 26        "date_announced": "23-06-2022 11:38:23",
 27        "date_updated": "23-06-2022 11:38:24",
 28        "email": "john@doe.com",
 29        "name": "John Doe",
 30        "postal_code": "BL1 8RG",
 31        "reference": "0",
 32        "shipment":
 33        {
 34            "id": 358,
 35            "name": "DHL Parcel Connect 2-5kg"
 36        },
 37        "status":
 38        {
 39            "id": 1000,
 40            "message": "Ready to send"
 41        },
 42        "to_service_point": null,
 43        "telephone": "+31611223344",
 44        "tracking_number": "JVGL05931316001606061101",
 45        "weight": "3.490",
 46        "label":
 47        {
 48            "normal_printer":
 49            [
 50                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0",
 51                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=1",
 52                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=2",
 53                "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=3"
 54            ],
 55            "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/1"
 56        },
 57        "customs_declaration":
 58        {
 59            "normal_printer": "https://panel.sendcloud.sc/api/v2/customs_declaration/normal_printer/1"
 60        },
 61        "order_number": "5020",
 62        "insured_value": 0,
 63        "total_insured_value": 0,
 64        "to_state": null,
 65        "customs_invoice_nr": "12345",
 66        "customs_shipment_type": 2,
 67        "parcel_items":
 68        [
 69            {
 70                "description": "T-Shirt",
 71                "quantity": 2,
 72                "weight": "0.900",
 73                "value": "19.95",
 74                "hs_code": "42022110",
 75                "origin_country": "SE",
 76                "product_id": "898678671",
 77                "properties":
 78                {
 79                    "size": "Medium",
 80                    "color": "Blue"
 81                },
 82                "sku": "TST-OD2019-B620",
 83                "return_reason": null,
 84                "return_message": null
 85            },
 86            {
 87                "description": "Laptop",
 88                "quantity": 1,
 89                "weight": "1.690",
 90                "value": "876.97",
 91                "hs_code": "42022110",
 92                "origin_country": "DE",
 93                "product_id": "5756464758",
 94                "properties":
 95                {
 96                    "color": "Black",
 97                    "internal_storage": "2TB"
 98                },
 99                "sku": "LT-PN2020-B23",
100                "return_reason": null,
101                "return_message": null
102            }
103        ],
104        "documents":
105        [
106            {
107                "type": "commercial-invoice",
108                "size": "a4",
109                "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/commercial-invoice"
110            },
111            {
112                "type": "label",
113                "size": "a6",
114                "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/label"
115            }
116        ],
117        "type": "parcel",
118        "shipment_uuid": null,
119        "shipping_method": 358,
120        "external_order_id": "1",
121        "external_shipment_id": "",
122        "external_reference": "12345",
123        "is_return": false,
124        "note": "",
125        "to_post_number": "",
126        "total_order_value": "896.92",
127        "total_order_value_currency": "EUR",
128        "colli_tracking_number": "",
129        "colli_uuid": "00a48af7-581e-46d7-94c5-6e7e65e1935b",
130        "collo_nr": 0,
131        "collo_count": 1,
132        "awb_tracking_number": null,
133        "box_number": null,
134        "length": "31.50",
135        "width": "27.20",
136        "height": "12.70",
137        "shipping_method_checkout_name": "Battery WarehouseX DHL",
138        "carrier":
139        {
140            "code": "dhl"
141        },
142        "tracking_url": "https://sendcloudfr.shipping-portal.com/tracking/?country=gb&tracking_number=jvgl05931316001606061101&postal_code=bl1+8rg"
143    }
144}'

Example response

  1{
  2    "parcel":
  3    {
  4        "id": 1,
  5        "address": "70 Flowers Avenue",
  6        "address_2": "",
  7        "address_divided":
  8        {
  9            "street": "Flowers Avenue",
 10            "house_number": "70"
 11        },
 12        "city": "Bolton",
 13        "company_name": "FlowerShop",
 14        "country":
 15        {
 16            "iso_2": "GB",
 17            "iso_3": "GBR",
 18            "name": "United Kingdom"
 19        },
 20        "data":
 21        {},
 22        "date_created": "23-06-2022 11:38:22",
 23        "date_announced": "23-06-2022 11:38:23",
 24        "date_updated": "23-06-2022 11:38:24",
 25        "email": "john@doe.com",
 26        "name": "John Doe",
 27        "postal_code": "BL1 8RG",
 28        "reference": "0",
 29        "shipment":
 30        {
 31            "id": 358,
 32            "name": "DHL Parcel Connect 2-5kg"
 33        },
 34        "status":
 35        {
 36            "id": 1000,
 37            "message": "Ready to send"
 38        },
 39        "to_service_point": null,
 40        "telephone": "+31611223344",
 41        "tracking_number": "JVGL05931316001606061101",
 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            "normal_printer": "https://panel.sendcloud.sc/api/v2/customs_declaration/normal_printer/1"
 57        },
 58        "order_number": "5020",
 59        "insured_value": 0,
 60        "total_insured_value": 0,
 61        "to_state": null,
 62        "customs_invoice_nr": "12345",
 63        "customs_shipment_type": 2,
 64        "parcel_items":
 65        [
 66            {
 67                "description": "T-Shirt",
 68                "quantity": 2,
 69                "weight": "0.900",
 70                "value": "19.95",
 71                "hs_code": "42022110",
 72                "origin_country": "SE",
 73                "product_id": "898678671",
 74                "properties":
 75                {
 76                    "size": "Medium",
 77                    "color": "Blue"
 78                },
 79                "sku": "TST-OD2019-B620",
 80                "return_reason": null,
 81                "return_message": null
 82            },
 83            {
 84                "description": "Laptop",
 85                "quantity": 1,
 86                "weight": "1.690",
 87                "value": "876.97",
 88                "hs_code": "42022110",
 89                "origin_country": "DE",
 90                "product_id": "5756464758",
 91                "properties":
 92                {
 93                    "color": "Black",
 94                    "internal_storage": "2TB"
 95                },
 96                "sku": "LT-PN2020-B23",
 97                "return_reason": null,
 98                "return_message": null
 99            }
100        ],
101        "documents":
102        [
103            {
104                "type": "commercial-invoice",
105                "size": "a4",
106                "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/commercial-invoice"
107            },
108            {
109                "type": "label",
110                "size": "a6",
111                "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/label"
112            }
113        ],
114        "type": "parcel",
115        "shipment_uuid": null,
116        "shipping_method": 358,
117        "external_order_id": "1",
118        "external_shipment_id": "",
119        "external_reference": "12345",
120        "is_return": false,
121        "note": "",
122        "to_post_number": "",
123        "total_order_value": "896.92",
124        "total_order_value_currency": "EUR",
125        "colli_tracking_number": "",
126        "colli_uuid": "00a48af7-581e-46d7-94c5-6e7e65e1935b",
127        "collo_nr": 0,
128        "collo_count": 1,
129        "awb_tracking_number": null,
130        "box_number": null,
131        "length": "31.50",
132        "width": "27.20",
133        "height": "12.70",
134        "shipping_method_checkout_name": null,
135        "carrier":
136        {
137            "code": "dhl"
138        },
139        "tracking_url": "https://sendcloudfr.shipping-portal.com/tracking/?country=gb&tracking_number=jvgl05931316001606061101&postal_code=bl1+8rg"
140    }
141}

Downloading customs documents

From the example response above, you can see that a successful API call will return the customs documents for the parcel under the documents object:

 1"documents":
 2[
 3	{
 4		"type": "commercial-invoice",
 5		"size": "a4",
 6		"link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/commercial-invoice"
 7	},
 8	{
 9		"type": "label",
10		"size": "a6",
11		"link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/label"
12	}
13]

In most cases, you’ll need to download and print the documents, ready to attach them to your parcel. Note that some carriers require multiple copies of the commercial invoice or CN23 form to be attached to the parcel.

You can download documents using the URL provided in the response, or via the Get parcel documents endpoint by providing the parcel_id. You’ll need to authenticate with your API credentials to access your documents.

Tip: Paperless trade

Sendcloud supports digital sending of customs documents for carriers who support Paperless trade. You can find a list of supporting carriers in this article.

Go to top