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