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:
- Specify the origin and destination country IDs. Use List all Countries API to find the country ID.
- 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.
- Specify the shipment charge. Request and compare rates for your shipment via Request Rates API.
- 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:
- 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.
- 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:
Name | Data type | Description |
---|---|---|
origin_country_id | integer | Country API ID of a country the shipment is made from. |
destination_country_id | integer | Country API ID of a country the shipment is made to. |
insurance_fee | number | Shipment insurance fee. |
shipment_charge | number | Shipment delivery fee. |
items | Array:duty_origin_country_id (integer)hs_code (string)customs_value (number) | Items to be shipped:duty_origin_country_id : item’s country of origin (manufacturer), can be obtained via the Country APIhs_code : 8-digit WTO Harmonised System (HS) code of an item, can be obtained via the HS code APIcustoms_value : item’s customs value based on its HS code group |
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.
Updated 11 months ago