International Shipping

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

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.

Custom Items

Property	Description
customs_item_id	identifier, generated To update a customs item, make sure to include the `customs_item_id` in shipment update request. NOTE: This value is meant to be generated by ShipEngine. Providing a "customs_item_id" in your initial request will cause an error.
description	string, required Include a short description of the product you are shipping.
quantity	integer, required Minimum of 1, number of items.
value	decimal, required The declared customs value of the item.
harmonized_tariff_code	string Harmonization Codes as standardized by the World Customs Organization. See below.
country_of_origin	string, required Two letter country code as it corresponds to ISO 3166-1 alpha-2.

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	Description
contents	enumerated string, required Choose one of: `gift`, `merchandise`, `returned_goods`, `documents`, `sample`
non_delivery	enumerated string, required `treat_as_abandoned`, `return_to_sender`
custom_items	array of Customs Item's, required

API Example

POST /v1/labels

Now that you understand the Custom's Object, we can drop that into a basic label request.

We added the customs object under the weight:

{
  "customs": {
    "contents": "documents",
    "non_delivery": "treat_as_abandoned",
    "customs_items": [
      {
        "description": "letter",
        "quantity": 1,
        "value": 1,
        "harmonized_tariff_code": "4817.20",
        "country_of_origin": "US"
      }
    ]
  }
}

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

Customs Form Download

Be sure to also download the form_download if the value is present. Some carriers, require a form to be included with your shipment. In many cases, we transmit this data electronically (EDI & ETD) when generating your label. (See Do my customs forms get transmitted electronically? in the ShipEngine Knowledge Base).

When using USPS, your customs forms print with your label, which you can see in the example above!

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipment": {
    "service_code": "usps_priority_mail_international",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "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"
    },
    "customs": {
      "contents": "documents",
      "customs_items": [
        {
          "description": "letter",
          "quantity": 1,
          "value": 1.0,
          "harmonized_tariff_code": "4817.20",
          "country_of_origin": "US"
        }
      ],
      "non_delivery": "treat_as_abandoned"
    },
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  }
}'

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
}