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 Shipments request. International shipments must include the required fields for the customs object and the required fields for the tax_identifiers array of objects. You may also need to add specific details like harmonized_tarrif_code and vat_rate to the products array of objects.

The Customs Object

PropertyTypeRequiredDescription
contentsenumerated string✔The contents of the shipment. Valid values include the following:

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 provided as other )
non_deliveryenumerated string✔Indicates what should be done if the shipment cannot be delivered. Valid values include the following:

treat_as_abandoned
return_to_sender
terms_of_trade_codeenumerated stringSpecifies the supported terms of trade code (incoterms). Valid values include the following:

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 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 objects✔Deprecated - please provide this information in the Products array inside Packages.
Customs declarations for each item in the shipment.

Products - Array of Objects: products

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 those properties to be the products array of objects, located inside the packages array of objects:

PropertyTypeRequiredDescription
descriptionstring✔<= 100 characters Nullable

A short description of the item in this package.
valueobject✔<int32> >=0

The declared value of each item.
Object includes 2 properties: currency and amount.
--> currencystring✔ShipEngine supports those currencies specified by ISO 4217.
--> amountnumber✔<double> >= 0

The monetary amount, in the specified currency.
weightobject✔The item weight. Object includes 2 properties: value and unit.
--> valuenumber✔<double> > 0

The weight, in the specified unit.
--> unitstring✔The possible weight unit values. Valid values are:
"pound"
"ounce"
"gram"
"kilogram"
harmonized_tariff_codestring, NullableThe Harmonization Codes, as standardized by the World Customs Organization. See the Harmonization Codes section below for more information.
country_of_originstring, NullableThe 2-character country code as it corresponds to ISO 3166-1 alpha-2.
unit_of_measurestring, NullableThe 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_descriptionstring, NullableA description of the SKU.
mid_codestring, NullableManufacturers Identification code.
product_urlstring, NullableLink to the item on the seller website.
vat_ratestring, Nullable <double>VAT rate applicable to the item.

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.

The Tax Identifiers Object

ShipEngine supports adding tax IDs to your shipment to comply with current International shipping requirements. Note that tax_identifiers array 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 the following:

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 type of this tax identifier. Valid values include the following:

vat - The tax identifier is a Value Added Tax.
eori - The tax identifier is an Economic Operators Registration and Identification Number (EORI).
ssn - The tax identifier is a Social Security Number.
ein - The tax identifier is an Employer Identification Number (EIN).
tin - The tax identifier is a Tax Identification Number (TIN).
ioss - The tax identifier is an Import One-Stop Shop (IOSS).
pan - The tax identifier is a Permanent Account Number (PAN).
voec - The tax identifier is a Norwegian VAT On E-Commerce(VOEC).
pccc - The tax identifier is a Personal Customs Clearance Code (PCCC).
oss - The tax identifier is a One-Stop Shop (OSS).
passport - The tax identifier is a Passport Number.
abn - The tax identifier is an Australian Business Number.
valuestring✔The value of the identifier.
issuing_authoritystring✔The authority that issued this tax. This must be a valid 2-character ISO 3166 Alpha 2 country code.

API Example

POST /v1/labels

Now that you understand the Customs Object, the Products array, and the Tax Identifiers Object, we can drop those into a basic label request by adding a customs object and a tax_identifiers object, like this:

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
"customs": {
       "contents": "merchandise",
       "contents_explanation": "required if contents = other",
       "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. The exporter of the products covered by this document declares that, except where otherwise clearly indicated, these products are of specified preferential origin as indicated under column C/T/O on this document.<br>The exporter of the products covered by this document (Exporter Reference No ... (1)) declares that, except where otherwise clearly indicated, these products are of ...(2) preferential origin.<br> Washington Convention of March 3 1973 Complaint Goods Non-taxable operation according to article 8, letter a) of Presidential Decree n. 633 of 1972. Goods do not contain dog and cat fur according to article - REG CEE 1523/2007 L 343",
       "invoice_additional_details": {
            "freight_charge": {
            "amount": 10.1,
            "currency": "USD"
        },
        "insurance_charge": {
            "amount": 11.1,
            "currency": "USD"
        },
        "other_charge": {
            "amount": 11,
            "currency": "USD"
        },
        "discount": {
            "amount": 10,
            "currency": "USD"
        },
        "other_charge_description": "description"




       },
  "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": {
         "0": {
           "currency": "usd",
           "amount": 0
         },
         "currency": "string",
         "amount": 0
       },
       "label_messages": {
         "reference1": null,
         "reference2": null,
         "reference3": null
       },
       "external_package_id": "string"
     }
   ]
 }
"tax_identifiers": [
  {
    "taxable_entity_type": "shipper",
    "identifier_type": "eori",
    "value": "GB987654312000",
    "issuing_authority": "GB"
   }
 ]

Example Request

Here is a full example request.

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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
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",
     "customs": {
       "contents": "merchandise",
       "contents_explanation": "required if contents = other",
       "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. The exporter of the products covered by this document declares that, except where otherwise clearly indicated, these products are of specified preferential origin as indicated under column C/T/O on this document.<br>The exporter of the products covered by this document (Exporter Reference No ... (1)) declares that, except where otherwise clearly indicated, these products are of ...(2) preferential origin.<br> Washington Convention of March 3 1973 Complaint Goods Non taxable operation according to article 8, letter a) of Presidential Decree n. 633 of 1972. Goods do not contain dog and cat fur according to article - REG CEE 1523/2007 L 343",
       "invoice_additional_details": {
            "freight_charge": {
            "amount": 10.1,
            "currency": "USD"
        },
        "insurance_charge": {
            "amount": 11.1,
            "currency": "USD"
        },
        "other_charge": {
            "amount": 11,
            "currency": "USD"
        },
        "discount": {
            "amount": 10,
            "currency": "USD"
        },
        "other_charge_description": "description"
       },
    "tax_identifiers": [
      {
        "taxable_entity_type": "shipper",
        "identifier_type": "eori",
        "value": "GB987654312000",
        "issuing_authority": "GB"
      }
    ],
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "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"
    },
    "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": {
         "0": {
           "currency": "usd",
           "amount": 0
         },
         "currency": "string",
         "amount": 0
       },
       "label_messages": {
         "reference1": null,
         "reference2": null,
         "reference3": null
       },
       "external_package_id": "string"
     }
   ]
 }
}

Example Response

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": "se-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"
}

You can now print your label and ship it! Your label and customs form can be found by navigating to label_download.href and links.form_download in the response, respectively.

Prepay Duties and Taxes for Canada Shipments

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 determined by the USPS international service you select:

  • First-Class Mail International: $7.95
  • Priority Mail International and Priority Mail Express International: $9.95

DDP is specified in your Create Label requests as an Advanced Option. The flat fee will display in the other_amount field of the rate response.

Example Request

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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
{
      "shipment":{
      "ship_to": {
         "name": "Kris Kringle",
         "phone": "(222) 333-4444",
         "company_name": null,
        "address_line1": "490 Sussex Dr",
         "address_line2": null,
        "city_locality": "Ottawa",
         "state_province": "ON",
         "postal_code": "K1N 1G8",
         "country_code": "CA",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "name": "Tiny Tim",
        "phone": "333-444-5555",
        "company_name": "Christmas Cove",
        "address_line1": "2171 ME-129",
        "city_locality": "South Bristol",
        "state_province": "ME",
        "postal_code": "04568",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "advanced_options": {
        "canada_delivered_duty":"sender_prepay"
    },
     "customs": {
       "contents": "merchandise",
       "contents_explanation": "required if contents = other",
       "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. The exporter of the products covered by this document declares that, except where otherwise clearly indicated, these products are of specified preferential origin as indicated under column C/T/O on this document.<br>The exporter of the products covered by this document (Exporter Reference No ... (1)) declares that, except where otherwise clearly indicated, these products are of ...(2) preferential origin.<br> Washington Convention of March 3 1973 Complaint Goods Non taxable operation according to article 8, letter a) of Presidential Decree n. 633 of 1972. Goods do not contain dog and cat fur according to article - REG CEE 1523/2007 L 343",
       "invoice_additional_details": {
            "freight_charge": {
            "amount": 10.1,
            "currency": "USD"
        },
        "insurance_charge": {
            "amount": 11.1,
            "currency": "USD"
        },
        "other_charge": {
            "amount": 11,
            "currency": "USD"
        },
        "discount": {
            "amount": 10,
            "currency": "USD"
        },
        "other_charge_description": "description"




       },
       "importer_of_record": {
         "name": "John Doe",
         "company_name": "The Home Depot",
         "address_line1": "1999 Bishop Grandin Blvd.",
         "address_line2": "Unit 408",
         "city_locality": "Winnipeg",
         "state_province": "Manitoba",
         "postal_code": "78756-3717",
         "country_code": "CA",
         "phone": "+1 204-253-9411 ext. 123",
      "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": {
         "0": {
           "currency": "usd",
           "amount": 0
         },
         "currency": "string",
         "amount": 0
       },
       "label_messages": {
         "reference1": null,
         "reference2": null,
         "reference3": null
       },
       "external_package_id": "string"
     }
   ]
 }
}

Example Response

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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{
    "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": 7.9500
                },
                "zone": null,
                "package_type": "package",
                "delivery_days": null,
                "guaranteed_service": false,
                "estimated_delivery_date": null,
                "carrier_delivery_days": null,
                "ship_date": "2022-11-04T00:00:00Z",
                "negotiated_rate": false,
                "service_type": "USPS First Class Mail Intl",
                "service_code": "usps_first_class_mail_international",
                "trackable": false,
                "carrier_code": "stamps_com",
                "carrier_nickname": "My Stamps account",
                "carrier_friendly_name": "Stamps.com",
                "validation_status": "valid",
                "warning_messages": [],
                "error_messages": []
            },
        ],
        "invalid_rates": [],
        "rate_request_id": "se-301944927",
        "shipment_id": "se-458174406",
        "created_at": "2022-11-04T20:45:30.2987928Z",
        "status": "completed",
        "errors": []
    },
    "shipment_id": "se-456",
    "carrier_id": "se-123",
    "service_code": null,
    "external_shipment_id": null,
    "shipment_number": null,
    "ship_date": "2022-11-04T00:00:00Z",
    "created_at": "2022-11-04T20:45:29.773Z",
    "modified_at": "2022-11-04T20:45:29.77Z",
    "shipment_status": "pending",
    "ship_to": {
        "name": "Kris Kringle",
        "phone": "(222) 333-4444",
        "company_name": null,
        "address_line1": "490 Sussex Dr",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "Ottawa",
        "state_province": "ON",
        "postal_code": "K1N 1G8",
        "country_code": "CA",
        "address_residential_indicator": "yes"
    },
    "ship_from": {
        "name": "Tiny Tim",
        "phone": "333-444-5555",
        "company_name": "Christmas Cove",
        "address_line1": "2171 ME-129",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "South Bristol",
        "state_province": "ME",
        "postal_code": "04568",
        "country_code": "US",
        "address_residential_indicator": "unknown"
    },
    "warehouse_id": null,
    "return_to": {
        "name": "Tiny Tim",
        "phone": "333-444-5555",
        "company_name": "Christmas Cove",
        "address_line1": "2171 ME-129",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "South Bristol",
        "state_province": "ME",
        "postal_code": "04568",
        "country_code": "US",
        "address_residential_indicator": "unknown"
    },
    "confirmation": "none",
    "customs": {
        "contents": "documents",
        "customs_items": [
        {
          "description": "letter to Santa",
          "quantity": 1,
          "value": {
            "currency": "usd",
            "amount": 10
            }
          "weight": {
            "value": 6,
            "amount":  "ounce"
            }
                "harmonized_tariff_code": "4817.20",
                "country_of_origin": "US",
                "unit_of_measure": null
         }
        ],
        "non_delivery": "treat_as_abandoned",
        "buyer_shipping_amount_paid": null,
        "duties_paid": null
    },
    "external_order_id": null,
    "order_source_code": null,
    "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "delivered_duty_paid": false,
        "non_machinable": false,
        "saturday_delivery": false,
        "dry_ice": false,
        "dry_ice_weight": null,
        "fedex_freight": null,
        "third_party_consignee": false,
        "ancillary_endorsements_option": null,
        "freight_class": null,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null,
        "collect_on_delivery": null,
        "return_pickup_attempts": null,
        "additional_handling": false
    },
    "insurance_provider": "none",
    "tags": [],
    "packages": [
        {
            "package_id": "se-3",
            "package_code": "package",
            "package_name": "Package",
            "weight": {
                "value": 6.00,
                "unit": "ounce"
            },
            "dimensions": {
                "unit": "inch",
                "length": 0.0,
                "width": 0.0,
                "height": 0.0
            },
            "insured_value": {
                "currency": "usd",
                "amount": 0.00
            },
            "label_messages": {
                "reference1": null,
                "reference2": null,
                "reference3": null
            },
            "external_package_id": null
        }
    ],
    "total_weight": {
        "value": 6.00,
        "unit": "ounce"
    },
    "items": []
}

International Shipping FAQ

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.

Bill of Lading for Shipments to and from Mexico (Carta Porte)

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 Request

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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
    "shipments": [
        {
            "validate_address": "no_validation",
            "carrier_id": "se-139088",
            "service_code": "international_delivery",
            "ship_to": {
                "name": "Jane Doe",
                "address_line1": "Av. Cuauhtémoc 462",
                "address_line2": "Piedad Narvarte",
                "address_line3": "Benito Juárez",
                "city_locality": "Ciudad de México",
                "state_province": "CDMX",
                "postal_code": "03020",
                "country_code": "MX",
                "phone": "555-555-5555",
                "address_residential_indicator": "no"
            },
            "ship_from": {
                "company_name": "Example Corp.",
                "name": "John Doe",
                "phone": "111-111-1111",
                "address_line1": "4009 Marathon Blvd",
                "address_line2": "Suite 300",
                "city_locality": "Austin",
                "state_province": "TX",
                "postal_code": "78756",
                "country_code": "US",
                "address_residential_indicator": "no"
            },
 "customs": {
       "contents": "merchandise",
       "contents_explanation": "required if contents = other",
       "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. The exporter of the products covered by this document declares that, except where otherwise clearly indicated, these products are of specified preferential origin as indicated under column C/T/O on this document.<br>The exporter of the products covered by this document (Exporter Reference No ... (1)) declares that, except where otherwise clearly indicated, these products are of ...(2) preferential origin.<br> Washington Convention of March 3 1973 Complaint Goods Non taxable operation according to article 8, letter a) of Presidential Decree n. 633 of 1972. Goods do not contain dog and cat fur according to article - REG CEE 1523/2007 L 343",
       "invoice_additional_details": {
            "freight_charge": {
            "amount": 10.1,
            "currency": "USD"
        },
        "insurance_charge": {
            "amount": 11.1,
            "currency": "USD"
        },
        "other_charge": {
            "amount": 11,
            "currency": "USD"
        },
        "discount": {
            "amount": 10,
            "currency": "USD"
        },
        "other_charge_description": "description"


       },


"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": {
         "0": {
           "currency": "usd",
           "amount": 0
         },
         "currency": "string",
         "amount": 0
       },
       "label_messages": {
         "reference1": null,
         "reference2": null,
         "reference3": null
       },
       "external_package_id": "string"
     }
   ]
 }
}


                }

Example Response

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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
{
    "has_errors": false,
    "shipments": [
        {
            "errors": [],
            "address_validation": null,
            "shipment_id": "se-8204558",
            "carrier_id": "se-139088",
            "service_code": "international_delivery",
            "external_shipment_id": null,
            "shipment_number": null,
            "ship_date": "2023-02-27T00:00:00Z",
            "created_at": "2023-02-27T20:20:06.6863638Z",
            "modified_at": "2023-02-27T20:20:06.6238761Z",
            "shipment_status": "pending",
        },
            "ship_to": {
                "instructions": null,
                "name": "Jane Doe",
                "phone": "555-555-5555",
                "company_name": null,
                "address_line1": "Av. Cuauhtémoc 462",
                "address_line2": "Piedad Narvarte",
                "address_line3": "Benito Juárez",
                "city_locality": "Ciudad de México",
                "state_province": "CDMX",
                "postal_code": "03020",
                "country_code": "MX",
                "address_residential_indicator": "no"
            },
            "ship_from": {
                "instructions": null,
                "name": "John Doe",
                "phone": "111-111-1111",
                "company_name": "Example Corp.",
                "address_line1": "4009 Marathon Blvd",
                "address_line2": "Suite 300",
                "address_line3": null,
                "city_locality": "Austin",
                "state_province": "TX",
                "postal_code": "78756",
                "country_code": "US",
                "address_residential_indicator": "unknown"
            },
            "warehouse_id": null,
            "return_to": {
                "instructions": null,
                "name": "John Doe",
                "phone": "111-111-1111",
                "company_name": "Example Corp.",
                "address_line1": "4009 Marathon Blvd",
                "address_line2": "Suite 300",
                "address_line3": null,
                "city_locality": "Austin",
                "state_province": "TX",
                "postal_code": "78756",
                "country_code": "US",
                "address_residential_indicator": "unknown"
            },
            "confirmation": "none",
                 "customs": {
       "contents": "merchandise",
       "contents_explanation": "required if contents = other",
       "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. The exporter of the products covered by this document declares that, except where otherwise clearly indicated, these products are of specified preferential origin as indicated under column C/T/O on this document.<br>The exporter of the products covered by this document (Exporter Reference No ... (1)) declares that, except where otherwise clearly indicated, these products are of ...(2) preferential origin.<br> Washington Convention of March 3 1973 Complaint Goods Non taxable operation according to article 8, letter a) of Presidential Decree n. 633 of 1972. Goods do not contain dog and cat fur according to article - REG CEE 1523/2007 L 343",
       "invoice_additional_details": {
            "freight_charge": {
            "amount": 10.1,
            "currency": "USD"
        },
        "insurance_charge": {
            "amount": 11.1,
            "currency": "USD"
        },
        "other_charge": {
            "amount": 11,
            "currency": "USD"
        },
        "discount": {
            "amount": 10,
            "currency": "USD"
        },
        "other_charge_description": "description"
       },
       "importer_of_record": {
         "name": "John Doe",
         "company_name": "The Home Depot",
         "address_line1": "1999 Bishop Grandin Blvd.",
         "address_line2": "Unit 408",
         "city_locality": "Winnipeg",
         "state_province": "Manitoba",
         "postal_code": "78756-3717",
         "country_code": "CA",
         "phone": "+1 204-253-9411 ext. 123",
      "email": "[email protected]"
       },


            "external_order_id": null,
            "order_source_code": null,
            "advanced_options": {
                "bill_to_account": null,
                "bill_to_country_code": null,
                "bill_to_party": null,
                "bill_to_postal_code": null,
                "contains_alcohol": false,
                "delivered_duty_paid": false,
                "non_machinable": false,
                "saturday_delivery": false,
                "dry_ice": false,
                "dry_ice_weight": null,
                "fedex_freight": null,
                "third_party_consignee": false,
                "ancillary_endorsements_option": null,
                "freight_class": null,
                "custom_field1": null,
                "custom_field2": null,
                "custom_field3": null,
                "collect_on_delivery": null,
                "return_pickup_attempts": null,
                "additional_handling": false
            },
            "insurance_provider": "none",
            "tags": [],
            "packages": [
                {
                    "package_id": "se-3",
                    "package_code": "package",
                    "package_name": "Package",
                    "content_description": "4x SKU 4225-776-3234",
                    "weight": {
                        "value": 41.0,
                        "unit": "ounce"
                    },
                    "dimensions": {
                        "unit": "inch",
                        "length": 24.0,
                        "width": 12.0,
                        "height": 6.0
                    },
                    "insured_value": {
                        "currency": "usd",
                        "amount": 0.0
                    },
                    "label_messages": {
                        "reference1": null,
                        "reference2": null,
                        "reference3": null
                    },
                    "external_package_id": null
                }
            ],
            "total_weight": {
                "value": 41.0,
                "unit": "ounce"
            },
            "items": []
        }
    ]
}