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