Customs & Shipping Internationally

How do I ship internationally using the API?
How do I create a commercial invoice?
How do customs forms work?
Do my customs forms get transmitted electronically (EDI and ETD)?
Does EasyPost support Paperless Trade (PLT)? EDI? AES?
Does EasyPost support sending PLT and EDI automatically to carriers?
Do you expect to offer AES/ITN services in the future?
Can I use multiple tariff numbers for each CustomsItem object?
Can EasyPost automatically sign my customs forms?
Why do I have to supply customs information for domestic shipments going to Puerto Rico?
Do I always need to specify package value when filling out my CustomsInfo object?
Do I need to make a separate CustomsItem for each unique item in my shipment?
I can't find my tariff number, is it ok to enter the closest number it could be?
What is the difference between COD amount and CustomsItem value amount?
What's the difference between DDP, DAP, and DDU?

How do I ship internationally using the API?

To ship internationally using the EasyPost API, you’ll need three things:

1. A carrier account that has international reach
2. A service level that has international reach
3. Customs information

When creating the Shipment object, ensure that you populate the proper strings with the carrier and service level you intend to use for your international shipment. Then, make sure your CustomsInfo object is populated with the right customs information for your package.

For a detailed line-by-line basis on how to use our Shipment and CustomsInfo objects, check out our documentation here.

How do I create a commercial invoice?

Follow our Customs Guide. Your Shipment object contains a forms array that contains the commercial invoice you need.

How do customs forms work?

EasyPost customs forms work via our CustomsInfo object. Since most of our labels have customs information integrated directly onto the label, there usually isn’t a need to print out separate customs forms (unless the carrier specifically dictates it).

Take a look at our Customs Documentation to learn more.

Do my customs forms get transmitted electronically (EDI and ETD)?

Yes, we transmit all of your customs information electronically along with the label.

Does EasyPost support Paperless Trade (PLT)? EDI? AES?

We support PLT for DHL and EDI for FedEx and UPS.

As far as AES goes, you can file the information at AESDirect and get a number. That number goes into the CustomsInfo object in the eel_pfc field, which then gets transmitted to the carrier. From that point, whether or not the data is submitted electronically is up to the PLT/EDI support.

Does EasyPost support sending PLT and EDI automatically to carriers?

The PLT for DHL Express is submitted by default if possible. We also do the same for the EDI for UPS and FedEx.

The forms array is an attribute on the Shipment object which returns the commercial invoice, and the form itself will say whether or not it was submitted electronically. 

Do you expect to offer AES/ITN services in the future?

We don’t provide ITNs, but if you generate an ITN through AESDirect, we support passing that ITN through to the carriers. We have no immediate plans to build a direct integration with the AESDirect API.

Can I use multiple tariff numbers for each CustomsItem object?

No, you can only use one tariff number for each CustomsItem. You will need to create a new CustomsItem object for each harmonized code or tariff number, otherwise known as the hs_tariff_number in our API documentation. 

If you need to look up the correct harmonized code for your shipments hs_tariff_number, you can go to the Harmonized Tariff Schedule and enter the name of the CustomsItem you are searching for. You can then use that harmonized code into your CustomsItem code like this JSON example:

Can EasyPost automatically sign my customs forms?

Yes. You can use our API to sign customs declaration forms for international shipments. The CustomsInfo object has the customs_certify and customs_signer values that take the place of a physical signature.

• customs_certify is a boolean value (true, false) that takes the place of the signature on the physical customs form. This is how you indicate that the information you have provided in your customs declaration is accurate.

• customs_signer is the name of the person who is certifying that the information provided on the customs form is accurate. Use the name of the person in your organization who is responsible for this.

EasyPost submits all customs paperwork electronically by default when it is supported by the carrier and the specified destination. The Form lives within the Shipment object's Form array.

Each Form object will have a submitted_electronically attribute that will return true if the form was submitted electronically. If false, the customs documents that are generated in the Form object will need to be printed and attached to the shipment.

You can read more about customs declarations, customs forms, and signature options in the EasyPost API documentation at these links:

• Customs Items Documentation
• Customs Guide

Why do I have to supply customs information for domestic shipments going to Puerto Rico?

UPS considers shipments to Puerto Rico as international shipments, and as such, require customs information. If you prefer not to go through the customs process, you can ship your package using USPS. USPS considers Puerto Rico a domestic destination and will not require any customs information for any domestic packages.

Do I always need to specify package value when filling out my CustomsInfo object?

Yes. The CustomsItem package value must always be filled out and can not be a $0.00 value. It's important to remember that the package value is the monetary value of the contents within your shipment, not what the customer paid for it. If you don't want to keep track of the pricing, you can simply enter a 1 cent value to complete the form.

Do I need to make a separate CustomsItem for each unique item in my shipment?

Yes. You can generate separate harmonized codes for each item within a shipment using EasyPost.

CustomsInfo objects contain CustomsItem objects and all the necessary information for the generation of customs forms required for international shipping. You will need one CustomsItem object for each unique item that you enter into your customs information declaration, which you can read more about in our CustomsInfo API documentation.

For the same or similar items with the same harmonized code, you can set the CustomsItems object with a quantity of how many you have of that same item within your shipment. If you have 5 of that item, you set up the CustomsItems object and put 5 in the quantity field.

If your items have different harmonized code tariff numbers, you'll have to create CustomsItem objects for each different harmonized code tariff number within that shipments’ CustomsInfo.

Here is a JSON example of what your CustomsItems object should look like:

I can't find my tariff number, is it ok to enter the closest number it could be?

While you can enter a tariff number that is your best guess, this is not a recommended shipping practice. You can ensure that your international shipments are successfully processed through customs and make it to their end destination without delays with EasyPost.

Within our system, the tariff definition is called an hs_tariff_code. The “hs” stands for harmonized tariff schedule. While it is always best practice to provide the harmonized tariff schedule code or number in the shipments CustomsItem object, it is not a mandatory field that EasyPost requires. Using the correct hs_tariff_code code helps get your international package shipping through customs more quickly and efficiently. There are some carriers and destinations that might actually require the harmonized tariff schedule number. If you use a carrier that requires this number, you will need to search for and find the right hs_tariff_number for your product.

Your harmonized tariff schedule code number is important to get your package moved through customs without interruption. If the information in your CustomsInfo is incomplete or incorrect, it can cause delays for the recipient of the package while customs officials try to determine how long to hold the package, or even determine if they will release the package at all. 

If you can't find the exact harmonized tariff schedule code or the number for your product, try to be as descriptive as possible in your product details so you'll minimize the possibility of issues with customs fees or international shipment release.

Looking for more customs information? Check out our Customs Guide.

What is the difference between COD amount and CustomsItem value amount?

The cod_amount is the cash on delivery amount and differs from the customs_items value amount. Cash on delivery is similar to the term collect on delivery, meaning that the shipment must be paid for by the recipient at the time of delivery, or the shipment is returned to the sender.

The cod_amount attribute can be added to the shipment options as a string via the EasyPost API. This attribute is generally accompanied by cod_method. If you are using FedEx for shipping packages, you would also pass the cod_address_id within the options when creating the label, like this JSON example:

You can read about additional input values for these attributes on our API documentation page.

The customs_items value is the monetary value of each item included in your customs_info object. The customs_items object lives within the customs_info object. Any time you generate customs information for international shipments within EasyPost, you are required to fill out customs information to generate the necessary forms needed to get them processed through customs, ensuring accurate payment of customs fees and international shipment release in a timely fashion for the package recipient.

When you generate a shipping label for an international package with customs fees, you can enter the customs_items value into the details of the package via the customs_items value string. Here is a JSON example within our shipping API:

Please make sure you also add the currency that you are valuing your monetary value of items within the package, shown as  "currency": "USD”  above within the customs_items object.

More information about these shipping label options can be found at these links:

Customs Items API Documentation

Customs Info API Documentation

"options": {
    "incoterm": "DDP",
  }