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

Property Type Required Description
customs_item_id string ✔ 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.
description string
A short description of the product you are shipping.
quantity integer ✔ The number of items in the shipment. The minimum value is 1.
value decimal ✔ The declared customs value of each item.
harmonized_tariff_code string ✔ The Harmonization Codes as standardized by the World Customs Organization. See below.
country_of_origin string The two letter country code as it corresponds to ISO 3166-1 alpha-2.
sku string ✔ *required by some carriers The Stock Keeping Unit for this shipment. This value must be between 1 and 20 characters.
sku_description string A description of the sku.

Info

Harmonization Tariff Codes

You will need to be familiar with the specific advanced options. You should be able to List Carrier Advanced Options.

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

The Customs Object

Property Type Required Description
contents enumerated 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_delivery enumerated 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_items Customs 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

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

{
  "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"
  }
 ]
}

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.

Info

Forms Download

Be sure to also download the files in the form_download object if any are present. This is where you will find customs forms and commercial invoices.

When shipping with UPS, FedEx or DHL Express, ShipEngine is able to electronically submit your forms to the carrier. For other carriers, you will need to download and print any generated files and include them in your shipment.

When using USPS, your customs forms print with your label rather than as separate documents.

Example Request

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": "78 Queen Victoria St",
      "state_province": "LND",
      "postal_code": "EC4N 4SJ",
      "country_code": "GB",
      "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.0,
          "unit": "pound"
        }
      }
    ]
  }
}

Example Response

{
  "label_id": "se-test-202927780",
  "status": "processing",
  "shipment_id": "se-202927780",
  "ship_date": "2019-07-25T05:00:00.000Z",
  "create_at": "2019-07-25T15:24:46.657Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "tracking_number": "9999999999999",
  "is_return_label": false,
  "is_international": true,
  "batch_id": "",
  "carrier_id": "se-0",
  "service_code": "usps_priority_mail_international",
  "package_code": "package",
  "voided": false,
  "voided_at": null,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": false,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf",
    "png": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.png",
    "zpl": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.zpl",
    "href": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf"
  },
  "form_download": null,
  "insurance_claim": null
}