shipengine-logo

International Shipping

To ship internationally, your package will be required to go through customs in the destination country. You must know about laws, regulations, and customs procedures that preside over customs.

It's required that you send us a list of contents with their declared value while requesting your label. A custom's item comprises of the following properties.

Customs Items

PropertyTypeRequiredDescription
customs_item_idstring✔Do not include a customs_item_id when you create your shipment. One will be generated for you and returned in the response. Providing a customs_item_id in your initial request will cause an error.

You will need to include this identifier if you wish to update customs items when you make a request to update a shipment.
descriptionstring
A short description of the product you are shipping.
quantityinteger✔The number of items in the shipment. The minimum value is 1.
valuedecimal✔The declared customs value of each item.
harmonized_tariff_codestring✔The Harmonization Codes as standardized by the World Customs Organization. See below.
country_of_originstringThe two letter country code as it corresponds to ISO 3166-1 alpha-2.
skustring✔ *required by some carriersThe Stock Keeping Unit for this shipment. This value must be between 1 and 20 characters.
sku_descriptionstringA description of the sku.

Make sure to pay attention to the customs field, as it contains two other fields contents and non_delivery

The Customs Object

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

gift - The package contains a gift
merchandise - The package contains merchandise.
returned_goods - The package is a returned shipment.
documents - The package contains documents.
sample - The package contains a commercial sample, such as a flooring sample.
non_deliveryenumerated string✔Indicates what should be done if the shipment cannot be delivered. Valid values include the following:

treat_as_abandoned - Treat the shipment as abandoned.
return_to_sender - Return the shipment ot the sender.
custom_itemsCustoms Items[]✔An array of Customs Items associated with this shipment.

The Tax Identifiers Object

ShipEngine supports applying tax identifiers to your shipment to comply with the new Brexit Requirements. Note that these properties exist inside the shipment 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.
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).
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 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
{
  "customs": {
    "contents": "merchandise",
    "non_delivery": "treat_as_abandoned",
    "customs_items": [
      {
        "quantity": 4,
        "value": {
          "currency": "usd",
          "amount": 75,
          "sku": "4225-776-3234",
          "sku_description": "This is the sku description."
        },
        "harmonized_tariff_code": "4817.20",
        "country_of_origin": "US",
        "description": "video games"
      }
    ]
  },
  "tax_identifiers": [
    {
      "taxable_entity_type": "shipper",
      "identifier_type": "eori",
      "value": "GB987654312000",
      "issuing_authority": "GB"
    }
  ]
}

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
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",
      "non_delivery": "treat_as_abandoned",
      "customs_items": [
        {
          "quantity": 4,
          "value": {
            "currency": "usd",
            "amount": 75
          },
          "harmonized_tariff_code": "4817.20",
          "country_of_origin": "US",
          "description": "video games",
          "sku": "4225-776-3234",
          "sku_description": "This is the sku 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": [
      {
        "weight": {
          "value": 4,
          "unit": "pound"
        }
      }
    ]
  }
}

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 & 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: $6.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
{
      "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": "documents",
      "customs_items": [
        {
          "description": "letter to santa",
          "quantity": 1,
          "value": 1.0,
          "harmonized_tariff_code": "4817.20",
          "country_of_origin": "US"
        }
      ],
      "non_delivery": "treat_as_abandoned"
    },
      "packages": [
      {
        "package_code": "package",
        "weight": {
          "value": 6,
          "unit": "ounce"
        }
        }
      ]
    },
  "rate_options": {
    "carrier_ids": [
      "se-123"
    ]
  }
}

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
{
    "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": 6.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": [
            {
                "customs_item_id": "se-66782661",
                "description": "letter to santa",
                "quantity": 1,
                "value": 1.00,
                "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": []
}