Site Logo

International Shipments

To ship internationally, your package will be required to go through customs in the destination country. For your shipment to effectively pass through customs, include all the required customs declarations data in your create shipment request and create label request.

Requirements

International shipments must include the required properties for the customs, products, and tax_identifiers objects. You may also need to add specific details like harmonized_tarrif_code and vat_rate to each of the products in your shipment.

Specific properties may be required depending on which countries you are shipping to and which carriers you are using. Be sure to check with your carrier and customs authority if you are uncertain what details you need to include with your shipments.

Customs Object Properties

PropertyTypeRequiredDescription
contentsenumerated string✔The contents of the shipment. Valid values include:
gift
merchandise
returned_goods
documents
sample
other - The package contains something other than items listed above.
contents_explanationstringExplanation for contents (required if the contents is set to other ).
non_deliveryenumerated string✔Indicates what should be done if the shipment cannot be delivered. Valid values include:
treat_as_abandoned
return_to_sender
terms_of_trade_codeenumerated stringSpecifies the supported terms of trade code (incoterms). Valid values include:
exw
fca
cpt
cip
dpu
dap
ddp
fas
fob
cfr
cif
ddu
daf
deq
des
declarationstringDeclaration statement to be placed on the commercial invoice.
invoice_additional_detailsobjectThe additional information to put on a commercial invoice. See the full API Reference for object fields.
importer_of_recordobjectThe importer of records' address, anywhere in the world. See the full API Reference for object fields.
customs_itemsarray of objectsDeprecated - please provide this information in the products property inside Packages.
Customs declarations for each item in the shipment.
See the Products section for details about which fields to include.

Products Object

When you request an international shipping label, you are required to send ShipEngine a list of that shipment's contents, along with their declared values. The following table describes the properties available.

PropertyTypeRequiredDescription
descriptionstring✔<= 100 characters, Nullable
A short description of the item in this package.
valueobject✔The declared value of each item.
Object includes 2 properties: currency and amount.
value.currencystring✔ShipEngine supports those currencies specified by ISO 4217.
value.amountnumber✔The monetary amount, in the specified currency.
weightobject✔The item weight. Object includes 2 properties: value and unit.
weight.valuenumber✔The weight, in the specified unit.
weight.unitenumerated string✔The possible weight unit values. Valid values are:
pound
ounce
gram
kilogram
harmonized_tariff_codestringNullable
The Harmonization Codes, as standardized by the World Customs Organization. See the Harmonization Codes section below for more information.
country_of_originstringNullable
The 2-character country code as it corresponds to ISO 3166-1 alpha-2.
unit_of_measurestringNullable
The possible dimensions unit values.
skustring✔Nullable
The Stock Keeping Unit (SKU) for this item. This value must be between 1 and 20 characters.
Required only by some carriers.
sku_descriptionstringNullable
A description of the SKU.
mid_codestringNullable
Manufacturers Identification code.
product_urlstringNullable
Link to the item on the seller website.
vat_ratestringNullable
VAT rate applicable to the item.

Tax Identifiers Object

ShipEngine supports adding tax IDs to your shipment to comply with current international shipping requirements. Note that the tax_identifiers object exists inside the shipments object, so you will need to take this into account when creating both shipments and labels.

PropertyTypeRequiredDescription
taxable_entity_typeenumerated string✔The taxable entity type for this tax item. Valid values include:
shipper - The shipper is responsible for this tax.
recipient - The recipient of the shipment is responsible for this tax.
ior - The importer of record is responsible for the tax.
identifier_typeenumerated string✔The tax identifier type. Valid values include:
vat
eori
ssn
ein
tin
ioss
pan
voec
pccc
oss
passport
abn
ukims
valuestring✔The actual tax id number.
issuing_authoritystring✔The authority that issued this tax. This must be a valid 2-character ISO 3166 Alpha 2 country code.

Downloading Forms

Any forms you will need to include with your shipment will be in the form_download object. In some cases, the form_download object will be empty, as is the case with electronic submissions or carriers that print customs details directly on the label (like USPS).

  • When shipping with UPS, FedEx or DHL Express, ShipEngine can electronically submit your forms to the carrier.
  • When using USPS, your customs forms print with your label rather than as separate documents.
  • For other carriers, you will need to download and print any generated files and include them in your shipment.

Example Request & Response

Now that you understand the objects required for international shipping, we can drop those into a basic label request by adding a products object, customs object, and tax_identifiers object.

POST /v1/labels

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"service_code": "usps_priority_mail_international",
"ship_from": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"email": "[email protected]",
"address_line1": "4301 Bull Creek Rd Ste. 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78731",
"country_code": "US",
"address_residential_indicator": "no"
},
"ship_to": {
"name": "John Doe",
"company_name": "Example Corp",
"address_line1": "Röntgenstr. 3",
"city_locality": "Esslingen am Neckar",
"state_province": "Stuttgart",
"postal_code": "73730",
"country_code": "DE",
"phone": "5555555555",
"email": "[email protected]"
},
"packages": [
{
"content_description": "Dog Toys",
"products": [
{
"quantity": 4,
"value": {
"currency": "usd",
"amount": 75
},
"sku": "4225-776-3234",
"sku_description": "Rubber-Ball",
"harmonized_tariff_code": "4016.99.20",
"country_of_origin": "US",
"description": "Pet Chew Toy",
"product_url": "https://tinyurl.com/adorable-womabt",
"mid_code": "123456",
"vat_rate": 0.02,
"weight": {
"value": 1,
"unit": "ounce"
}
},
{
"quantity": 2,
"value": {
"currency": "usd",
"amount": 100
},
"sku": "3001-776-3234",
"sku_description": "Tug-of-War-Rope",
"harmonized_tariff_code": "6307.90.75",
"country_of_origin": "US",
"description": "Cotton Pet Chew Toy",
"product_url": "https://tinyurl.com/adorable-womabt",
"mid_code": "123456",
"vat_rate": null,
"weight": {
"value": 2,
"unit": "ounce"
}
}
],
"package_id": "se-3",
"package_code": "package",
"weight": {
"value": 9.6,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 10.0,
"width": 8.0,
"height": 8.0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
}
],
"customs": {
"contents": "merchandise",
"non_delivery": "treat_as_abandoned",
"terms_of_trade_code": "DDP",
"declaration": "I hereby certify that the information on this invoice is true and correct and the contents and value of this shipment is as stated above.",
},
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "eori",
"value": "GB987654312000",
"issuing_authority": "GB"
}
]
}
}

Example Response

Note that the customs, products, and tax_identifier objects are not returned in the response. Any customs forms and commercial invoices you need to print will be returned in the form_download object. In this example, since it uses a USPS service, the customs details are printed directly on the label, so no additional forms are returned.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
"label_id": "se-120659535",
"status": "completed",
"shipment_id": "se-236919990",
"ship_date": "2022-01-04T00:00:00Z",
"created_at": "2022-01-04T19:34:43.6076942Z",
"shipment_cost": {
"currency": "usd",
"amount": 60.18
},
"insurance_cost": {
"currency": "usd",
"amount": 0.0
},
"tracking_number": "LX678657357US",
"is_return_label": false,
"rma_number": null,
"is_international": true,
"batch_id": "",
"carrier_id": "se-121493",
"service_code": "usps_priority_mail_international",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"display_scheme": "label",
"label_layout": "4x6",
"trackable": false,
"label_image_id": null,
"carrier_code": "stamps_com",
"tracking_status": "unknown",
"label_download": {
"pdf": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf",
"png": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.png",
"zpl": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.zpl",
"href": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf"
},
"form_download": null,
"insurance_claim": null,
"packages": [
{
"package_id": 127260247,
"package_code": "package",
"weight": {
"value": 4.00,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 0.0,
"width": 0.0,
"height": 0.0
},
"insured_value": {
"currency": "usd",
"amount": 0.00
},
"tracking_number": "LX678657357US",
"label_messages": {
"reference1": null,
"reference2": null,
"reference3": null
},
"external_package_id": null,
"sequence": 1
}
],
"charge_event": "carrier_default"
}

Your label and customs forms can be found by going to label_download.href and links.form_download in the response, respectively.

Shipping from US to Canada

If you ship from the US to Canada using USPS First-Class Mail International, Priority Mail International, or Priority Mail Express International, you have the option to create a Delivered Duty Paid (DDP) shipment.

When you create a DDP shipment, you will be charged a flat fee to pay duties or taxes in advance so that your recipient does not have to pay them upon delivery. The fee is $9.95 for all eligible services.

To use the pre-pay DDP option, add an advanced option object to your shipment object with the canada_delivered_duty property set to "sender_prepay".

1
2
3
4
5
6
7
{
"shipment":{
"advanced_options": {
"canada_delivered_duty":"sender_prepay"
},
}
}

Example Response

The flat fee will display in the other_amount field of the rate_response object. (This response is truncated to more easily demonstrate the relevant propery.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
"rate_response": {
"rates": [
{
"rate_id": "se-2095723696",
"rate_type": "shipment",
"carrier_id": "se-3377959",
"shipping_amount": {
"currency": "usd",
"amount": 14.11
},
"insurance_amount": {
"currency": "usd",
"amount": 0.0
},
"confirmation_amount": {
"currency": "usd",
"amount": 0.0
},
"other_amount": {
"currency": "usd",
"amount": 9.9500
},
"rate_details": []
}
],
"billing_source": "Carrier",
"rate_request_id": "se-301944927",
"shipment_id": "se-458174406",
"created_at": "2022-11-04T20:45:30.2987928Z",
"status": "completed",
"errors": []
},
}

Shipping to and from Mexico

The Mexican government requires all shipments to, from, and within Mexico to include a Bill of Lading Complement (Complemento Carta Porte). The Bill of Lading must include package-level merchandise descriptions, which are separate from traditional customs item information requirements.

To create a Bill of Lading with your shipping label and other customs documents, include the content_description property in the packages object of your label request.

For more information about the Carta Porte requirement, visit the Gobierno de México Servicio de Administración Tributaria page (Español) or the US International Trade Administration's Carta Porte page (English).

Example Packages Object

1
2
3
4
5
6
7
8
{
"packages": [
{
"content_description": "Dog Toys",
"products": []
}
]
}

Shipping to the EU

All shipments to and passing through most countries in the EU require Harmonization Codes to be included on customs forms with accurate descriptions of the package contents.

This means that descriptions such as "Clothes" will not be accepted. Instead, more detailed descriptions such as "Men's Cotton Shirt" or "Women's Leather Shoes" are required.

Learn more about the Harmonization Code requirement from the following resources:

International Shipping FAQ

What are Harmonization Codes?

The purpose of a Harmonization Code (also referred to as Tariff Codes, Customs Tariffs, Harmonized Tariff Codes, and Harmonized System Codes or HS Codes) is to expedite the delivery of international shipments. The system of codes for your goods is a universal economic language used to trade merchandise that is shipped internationally and assess taxes.

Once an order reaches an international border, the Harmonization Codes help the customs office to identify what it is you are shipping. We recommend that you list and properly identify your Harmonization Codes at the time of label creation.

For a full list of Harmonization Codes, use the Harmonized Tariff Schedule search.

Does ShipEngine print USMCA forms for international shipments?

Currently, ShipEngine does not receive USMCA forms (formerly called NAFTA forms) from carriers for international shipments. If you'd like to include a USMCA form with a shipment, you must download and fill out the form outside of ShipEngine.