Create an International Label

Learn how to use ShipEngine® to create a label that will ship to another country.

The Basics

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.

Customs Item

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.

Harmonization Tariff Codes

While not required, we encourage the use of harmonization codes. Harmonization codes introduce a standardized system to identify and classify a product for over 200 countries worldwide.

To include a Harmonization Code in your customs declaration, use one of the following services to lookup your item's code:

Additionally, you can check tariffs by region.

Without further ado, let's send a letter to Santa Claus. 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

customs_items

array of Customs Item's, required

/v1/labels

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

curl $apiUrl$/v1/labels -X POST \
  -H "Content-type: application/json" \
  -H $apiAuth$ \
  -d '
{
  "shipment": {
    "service_code": "usps_priority_mail_international",
    "ship_to": {
      "name": "Santa Clause",
      "address_line1": "North Pole",
      "city_locality": "North Pole",
      "state_province": "North Pole",
      "postal_code": "H0H 0H0",
      "country_code": "CA"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "country_code": "US",
      "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"
        }
      }
    ]
  }
}'

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"
    }
  ]
}
{
  "label_id": "se-test-202927780",
  "status": "processing",
  "shipment_id": "se-202927780",
  "ship_date": "$shipDate$",
  "create_at": "$date$",
  "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
}

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.

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!

Change customers_item_id to customs_item_id


Create an International Label


Learn how to use ShipEngine® to create a label that will ship to another country.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.