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
Property | Type | Required | Description |
---|---|---|---|
contents | enumerated 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_explanation | string | Explanation for contents (required if the contents is provided as other ) | |
non_delivery | enumerated 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_code | enumerated string | Specifies 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 | |
declaration | string | Declaration statement to be placed on the commercial invoice | |
invoice_additional_details | object | The additional information to put on commercial invoice See the full API Reference for object fields. | |
importer_of_record | object | The importer of records' address, anywhere in the world. See the full API Reference for object fields. | |
customs_items | array 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:
Property | Type | Required | Description |
---|---|---|---|
description | string | ✔ | <= 100 characters NullableA short description of the item in this package. |
value | object | ✔ | <int32> >=0 The declared value of each item. Object includes 2 properties: currency and amount . |
--> currency | string | ✔ | ShipEngine supports those currencies specified by ISO 4217. |
--> amount | number | ✔ | <double> >= 0 The monetary amount, in the specified currency. |
weight | object | ✔ | The item weight. Object includes 2 properties: value and unit . |
--> value | number | ✔ | <double> > 0 The weight, in the specified unit. |
--> unit | string | ✔ | The possible weight unit values. Valid values are: "pound" "ounce" "gram" "kilogram" |
harmonized_tariff_code | string, Nullable | The Harmonization Codes, as standardized by the World Customs Organization. See the Harmonization Codes section below for more information. | |
country_of_origin | string, Nullable | The 2-character country code as it corresponds to ISO 3166-1 alpha-2. | |
unit_of_measure | string, Nullable | The possible dimensions unit values | |
sku | string, Nullable | ✔ | The Stock Keeping Unit (SKU) for this item. This value must be between 1 and 20 characters. *required only by some carriers |
sku_description | string, Nullable | A description of the SKU. | |
mid_code | string, Nullable | Manufacturers Identification code. | |
product_url | string, Nullable | Link to the item on the seller website. | |
vat_rate | string, 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
Property | Type | Required | Description |
---|---|---|---|
taxable_entity_type | enumerated 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_type | enumerated 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. |
value | string | ✔ | The value of the identifier. |
issuing_authority | string | ✔ | 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:
Example Request
Here is a full example request.
Example Response
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
Example Response
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).