shipengine-logo

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

PropertyTypeRequiredDescription
customs_item_idstring✔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.
descriptionstring
A short description of the product you are shipping.
quantityinteger✔The number of items in the shipment. The minimum value is 1.
valuedecimal✔The declared customs value of each item.
harmonized_tariff_codestring✔The Harmonization Codes as standardized by the World Customs Organization. See below.
country_of_originstringThe two letter country code as it corresponds to ISO 3166-1 alpha-2.
skustring✔ *required by some carriersThe Stock Keeping Unit for this shipment. This value must be between 1 and 20 characters.
sku_descriptionstringA description of the sku.

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

The Customs Object

PropertyTypeRequiredDescription
contentsenumerated 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_deliveryenumerated 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_itemsCustoms 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

PropertyTypeRequiredDescription
taxable_entity_typeenumerated 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_typeenumerated 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).
ioss - The tax identifier is an Import One-Stop Shop (IOSS).
pan - The tax identifier is a Permanent Account Number (PAN).
voec - The tax identifier is a Norwegian VAT On E-Commerce(VOEC).
valuestring✔The value of the identifier.
issuing_authoritystring✔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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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"
    }
  ]
}

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
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": "4301 Bull Creek Rd Ste. 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78731",
      "country_code": "US",
      "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,
          "unit": "pound"
        }
      }
    ]
  }
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
    "label_id": "se-120659535",
    "status": "completed",
    "shipment_id": "se-236919990",
    "ship_date": "2022-01-04T00:00:00Z",
    "created_at": "2022-01-04T19:34:43.6076942Z",
    "shipment_cost": {
        "currency": "usd",
        "amount": 60.18
    },
    "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
    },
    "tracking_number": "LX678657357US",
    "is_return_label": false,
    "rma_number": null,
    "is_international": true,
    "batch_id": "",
    "carrier_id": "se-121493",
    "service_code": "usps_priority_mail_international",
    "package_code": "package",
    "voided": false,
    "voided_at": null,
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "trackable": false,
    "label_image_id": null,
    "carrier_code": "stamps_com",
    "tracking_status": "unknown",
    "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf",
        "png": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.png",
        "zpl": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.zpl",
        "href": "https://api.shipengine.com/v1/downloads/10/79vVrg0ovkSgviVkZS1csg/label-120659535.pdf"
    },
    "form_download": null,
    "insurance_claim": null,
    "packages": [
        {
            "package_id": 127260247,
            "package_code": "package",
            "weight": {
                "value": 4.00,
                "unit": "pound"
            },
            "dimensions": {
                "unit": "inch",
                "length": 0.0,
                "width": 0.0,
                "height": 0.0
            },
            "insured_value": {
                "currency": "usd",
                "amount": 0.00
            },
            "tracking_number": "LX678657357US",
            "label_messages": {
                "reference1": null,
                "reference2": null,
                "reference3": null
            },
            "external_package_id": null,
            "sequence": 1
        }
    ],
    "charge_event": "carrier_default"
}

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.