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_nr string Customs invoice number (DEPRECATED)
customs_shipment_type integer Customs shipment type. Accepted values are: 0 - Gift 1 - Documents, 2 Commercial Goods, 3 Commercal Sample, 4 - Returned Goods (DEPRECATED)
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, refer to Help Center.

Customs information object

The customs_information object contains optional customs information that could be provided for international parcels. This functionality is available only for beta feature users. Contact customer support or your Customer Success Manager if you want to use it.

To learn all of the parameter fields, refer to the Create a parcel section.

The following fields became deprecated:

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
from_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

Note that the object contains the following objects inside of the customs_information:

Parameter Type Required Description
importer_of_record object The parameter responsible for making sure imported goods meet all customs and legal rules of the importing country.
return_data object Only relevant when shipping a return parcel.
tax_numbers object Identification tax numbers and codes related to sender, receiver and importer of record provider.

The tax number validation is implemented with the following principles:

  • By Sender: the country code can match either the sender country code or the destination country code.
  • By Receiver or Importer of record: the country code can match only the destination country code
  • For IOSS, the country code can contain any value in the EU and does not follow the logic above.

Example

Before the customs_information introduction, your tax details could look like this

1       "from_vat_number": "NL000000005B55",
2        "from_eori_number": "NL000000005",
3        "from_inbound_vat_number": "GB000000005B66",

After its implementation, the tax information would look like this:

 1{
 2    "tax_numbers": {
 3        "sender": [
 4            {
 5                "name": "VAT",
 6                "country_code": "NL",
 7                "value": "NL000000005B55"
 8            },
 9            {
10                "name": "EORI",
11                "country_code": "NL",
12                "value": "NL000000005"
13            },
14            {
15                "name": "VAT",
16                "country_code": "GB",
17                "value": "GB000000005B66"
18            }
19        ],
20        "receiver": [ ... ],
21        "importer_of_record": [ ... ],
22    }
23}

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        "name": "John Doe",
 8        "company_name": "FlowerShop",
 9        "email": "john@doe.com",
10        "telephone": "+31611223344",
11        "address": "Flowers Avenue",
12        "house_number": "70",
13        "address_2": "",
14        "city": "Bolton",
15        "country": "GB",
16        "country_state": null,
17        "postal_code": "BL1 8RG",
18        "to_service_point": 217165,
19        "customs_invoice_nr": "12345",
20        "customs_shipment_type": 2,
21        "parcel_items":
22        [
23            {
24                "description": "T-Shirt",
25                "hs_code": "6109",
26                "origin_country": "SE",
27                "product_id": "898678671",
28                "properties":
29                {
30                    "color": "Blue",
31                    "size": "Medium"
32                },
33                "quantity": 2,
34                "sku": "TST-OD2019-B620",
35                "value": "19.95",
36                "weight": "0.9"
37            },
38            {
39                "description": "Laptop",
40                "hs_code": "84713010",
41                "origin_country": "DE",
42                "product_id": "5756464758",
43                "properties":
44                {
45                    "color": "Black",
46                    "internal_storage": "2TB"
47                },
48                "quantity": 1,
49                "sku": "LT-PN2020-B23",
50                "value": "876.97",
51                "weight": "1.69"
52            }
53        ],
54        "weight": "3.49",
55        "length": "31.5",
56        "width": "27.2",
57        "height": "12.7",
58        "total_order_value": "896.92",
59        "total_order_value_currency": "EUR",
60        "shipment":
61        {
62            "id": 358,
63            "name": "DHL Parcel Connect 2-5kg to ParcelShop"
64        },
65        "shipping_method_checkout_name": "Battery WarehouseX DHL",
66        "sender_address": 1,
67        "quantity": 1,
68        "total_insured_value": 0,
69        "is_return": false,
70        "request_label": true
71    }
72}'

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": 217165,
 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_uuid": "00a48af7-581e-46d7-94c5-6e7e65e1935b",
126        "collo_nr": 0,
127        "collo_count": 1,
128        "awb_tracking_number": null,
129        "box_number": null,
130        "length": "31.50",
131        "width": "27.20",
132        "height": "12.70",
133        "shipping_method_checkout_name": null,
134        "carrier":
135        {
136            "code": "dhl"
137        },
138        "tracking_url": "https://sendcloudfr.shipping-portal.com/tracking/?country=gb&tracking_number=jvgl05931316001606061101&postal_code=bl1+8rg"
139    }
140}

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.

On this page

Go to top