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

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",
    "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
}