🌐 Estimate duties/taxes

This endpoint allows you to estimate the import duties and taxes for your shipment based on a couple of parameters. We return the estimated amount per tax type (e.g. duty and VAT), the total estimate and the harmonized (HS) code we used for the calculation. If you successfully made a request to estimate the duties and taxes, it will look something like this:

Method

To estimate the duties and taxes, you need to use the following method:

POST

Endpoint

You need the following endpoint:

https://services.parcelparcel.com/partners-api/v1/duties-taxes-estimate

Header

You need to add the following headers:

Name	Value
Content-Type	application/json
X-PP-API	`{YourAPIKey}@{YourAPISecret}`
Don't you have an API Key and API Secret yet? Check our Authentication page and how to get them in under a minute.

Body

The Request body must contain a JSON structure with the following definition

Name	Value	Required	Comments
contentItems	(object array) Content item	true	More information is below. Each object describes a type of goods in your shipment used to calculate the duties and taxes.
fromCountry		true	You should provide the country in ISO-2 format (e.g. NL or US)
fromZipcode		false	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
fromCity		false	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
toCountry		true	You should provide the country in ISO-2 format (e.g. NL or US)
toZipcode		false	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
toCity		false	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.

Example Body

{
    "fromCountry": "NL",
    "toCountry": "GB",
    "fromCity": "Eindhoven",
    "fromZipcode": "5643TW",
    "toCity": "Gillingham",
    "toZipcode": "ME8 0RU",
    "contentItems": [
        {
            "description": "Cylinder head for compression-ignition diesel engine",
            "numberOfItems": 9,
            "cost": 800,
            "tariff": "84099900",
            "originCountry": "NL"
        }
    ]
}

Content item

Name	Value	Required	Comments
description	string	true	A clear description of the goods (e.g. "Cylinder head for compression-ignition diesel engine").
numberOfItems	integer	true	The number of units of this item in your shipment (e.g. 9).
cost	number	true	The value per item, stated in euros (€). This is used to calculate the customs value.
tariff	string	false	The HS (harmonized) code of the goods. If you don't provide one, we determine the most suitable code based on the description.
originCountry	string	false	The country of origin of the goods in ISO-2 format (e.g. NL).

Example content item:

{
    "description": "Cylinder head for compression-ignition diesel engine",
    "numberOfItems": 9,
    "cost": 800,
    "tariff": "84099900",
    "originCountry": "NL"
}

Response

The following response elements are returned:

Name	Value	Comments
hasErrors	bool	Indicates whether the request resulted in any errors.
taxDetails	array	A breakdown of the estimated duties and taxes per tax type.
taxDetails.harmonizedCode	string	The harmonized (HS) code used to calculate this tax line.
taxDetails.name	string	The name of the tax or duty (e.g. MFN [Most Favored Nation Applied Duty] or VAT [Value Added Tax]).
taxDetails.amount	number	The estimated amount for this tax type, returned in euros (€) with 2 decimals.
taxDetails.description	string	An optional description providing more context for this tax line.
estimate	number	The total estimated duties and taxes, returned in euros (€) with 2 decimals. This is the sum of all taxDetails amounts.
hsCode	string	The harmonized (HS) code we used for the estimate.

Please note, that the returned values are an estimate and the actual duties and taxes charged by customs may differ.

Examples

Below, we have created an example so you are up and running ASAP. Don't know how to test these requests? Check our guide.

Request example - Estimate duties & taxes for a parcel shipment from the Netherlands to the United Kingdom

curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/duties-taxes-estimate' \
--header 'X-PP-API: `{YourAPIKey}@{YourAPISecret}`' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fromCountry": "NL",
    "toCountry": "GB",
    "fromCity": "Eindhoven",
    "fromZipcode": "5643TW",
    "toCity": "Gillingham",
    "toZipcode": "ME8 0RU",
    "contentItems": [
        {
            "description": "Cylinder head for compression-ignition diesel engine",
            "numberOfItems": 9,
            "cost": 800,
            "tariff": "84099900",
            "originCountry": "NL"
        }
    ]
}'

POST /partners-api/v1/duties-taxes-estimate HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: `{YourAPIKey}@{YourAPISecret}`
Content-Type: application/json
{
    "fromCountry": "NL",
    "toCountry": "GB",
    "fromCity": "Eindhoven",
    "fromZipcode": "5643TW",
    "toCity": "Gillingham",
    "toZipcode": "ME8 0RU",
    "contentItems": [
        {
            "description": "Cylinder head for compression-ignition diesel engine",
            "numberOfItems": 9,
            "cost": 800,
            "tariff": "84099900",
            "originCountry": "NL"
        }
    ]
}

Don't forget to change the X-PP-API element in the header for this request to work. Don't know where to get your API Key and API Secret? Check our Authentication page and how to get them in under a minute.

Response example - Estimate duties & taxes for a parcel shipment from the Netherlands to the United Kingdom

{
    "hasErrors": false,
    "taxDetails": [
        {
            "harmonizedCode": "840999001000",
            "name": "MFN [Most Favored Nation Applied Duty]",
            "amount": 146.32,
            "description": ""
        },
        {
            "harmonizedCode": "840999001000",
            "name": "VAT [Value Added Tax; ; ]",
            "amount": 1492.48,
            "description": ""
        }
    ],
    "estimate": 1638.8,
    "hsCode": "8409990010"
}