How to Calculate Taxes and Duties

Easyship Taxes and Duties (T&D) feature allows to calculate taxes and duties applicable for an international shipment.

Endpoint description

The T&D feature is available via the T&D API endpoint:

POST https://api.easyship.com/2023-01/taxes_and_duties

In the response, you will obtain two fields containing calculated shipment tax and duty costs with details provided.

To calculate taxes and duties fees, follow these steps:

1. Specify the origin and destination country IDs. Use List all Countries API to find the country ID.
2. Enter the shipment insurance fee. You can automate insurance management with shipping rules. To learn more about how to insure your shipment, how insurance is calculated and how to file an insurance claim, refer to our Add Insurance to Shipments article.
3. Specify the shipment charge. Request and compare rates for your shipment via Request Rates API.
4. Provide the following information for each item to be shipped:
   a. duty_origin_country_id. Item’s country of origin (manufacturer). Use List all Countries API to find the country ID.
   b. hs_code. Eight-digit WTO Harmonised System (HS) code of a shipped item. Use List HS Codes API to find the code.
   c. customs_value. Item’s customs value based on its HS code group. Refer to our article on Declaring an Accurate Shipment Customs Value to learn more about how to declare your shipment value correctly and what happens when you don't.

📘

While Easyship uses up-to-date data to calculate related taxes and duties costs as precisely as possible, this feature currently has two limitations:

1. Non-percentage duty tariffs are not supported. Some countries (e.g. Switzerland) apply a one-off import duty fee instead of calculating percentage. These cases are currently not supported.
2. Import regulation changes. Some countries (e.g. Saudi Arabia) can change import regulations quickly and relatively often. Currently, Easyship may accommodate to such changes with a time gap.

Body parameters

The T&D request requires body with the following parameters:

All parameters from this table are required.

Request body example

{
  "items": [
    {
      "duty_origin_country_id": 78,
      "hs_code": "07051100",
      "customs_value": 490
    }
  ],
  "destination_country_id": 78,
  "origin_country_id": 69,
  "insurance_fee": 27,
  "shipment_charge": 90
}

Response examples

Successful response

In case of successful calculation, you will obtain a minimal 200 response with calculated amounts:

{
  tax: 600, //tax amount with rounding applied
  duty: 200 // duty amount with rounding applied
}

Errors

In case of any mistakes, you may obtain the following 400 error messages:

• origin_country_id is not included in the Easyship country list
• destination_country_id is not included in the Easyship country list
• insurance_fee is not a number
• shipment_charge is not a number

Additionally, you may see 400 errors related to specified items:

• Duty origin country is not included in the Easyship country list
• HS code is invalid
• customs_value is not a number

These errors will be indexed:

{
    "error": {
        "code": "invalid_content",
        "details": [
            "items[0]: Customs value is not a number"
        ],
        "message": "The request body content is not valid.",
        "request_id": "7ea683fa3611326e4602c289b660b1c1",
        "type": "invalid_request_error"
    }
}

In case of tax or duty calculation mistakes, you will obtain the following 422 errors:

{
  tax: "No import tax record was found for the specified origin and destination",
  duty: nil
}

{
  tax: nil
  duty: "Duty records not found for duty_origin_country_id and hs_code combinations: [[199, "1234"], [234, "123"]]"
}

Additional resources

To see more information on definitions, processes and best practices for managing trade regulations, refer to our Understanding Shipping Duties and Taxes page.

Research the tax thresholds for each country to see detailed tax, duties and customs information for the countries you are shipping to.

Use our T&D calculators to get a quick estimate.