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 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
Include a short description of the product you are shipping.
quantity integer
Minimum of 1, number of items.
value decimal, required
The declared customs value of each item.
harmonized_tariff_code string
Harmonization Codes as standardized by the World Customs Organization. See below.
country_of_origin string
Two letter country code as it corresponds to ISO 3166-1 alpha-2.
sku string, required by some carriers
Minimum of 1, maximum of 20 characters. The SKU or product identification number for the shipment.
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 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 Items, required

API Example

POST /v1/labels

Now that you understand the Custom's Object, we can drop that into a basic label request by adding a customs 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"
      }
    ]
  }
}

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",
    "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."
        }
      ]
    },
    "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": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "London",
      "state_province": "London",
      "postal_code": "EC4N 4SG",
      "country_code": "GB",
      "address_residential_indicator": "yes"
    },
    "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
}