Estimate duties/taxes

Markdown

Estimate the import duties and taxes of a shipment.

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

Example request

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

curl --request POST 'https://services.parcelparcel.com/partners-api/v1/duties-taxes-estimate' \
  --header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
    }
  ]
}'

{
  "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"
    }
  ]
}

const response = await fetch("https://services.parcelparcel.com/partners-api/v1/duties-taxes-estimate", {
  method: "POST",
  headers: {
    "X-PP-API": "{YourAPIKey}@{YourAPISecret}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
      }
    ]
  }),
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://services.parcelparcel.com/partners-api/v1/duties-taxes-estimate",
    headers={
        "X-PP-API": "{YourAPIKey}@{YourAPISecret}",
        "Content-Type": "application/json",
    },
    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",
            },
        ],
    },
)
print(response.json())

Tip: copy the cURL and paste it in Postman under Import, or straight into the URL bar of a new request. Postman fills in the method, headers and body for you. Replace {YourAPIKey}@{YourAPISecret} with your own API key and secret (use your sandbox key while testing), or import the whole Postman Collection.

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.

See the examples for a complete request and response. Not sure if a shipment goes through customs at all? Check the route first. For a route within the EU or a domestic route there are no import duties: you get an estimate of 0 and no taxDetails.

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	required	More information is below. Each object describes a type of goods in your shipment used to calculate the duties and taxes.
`fromCountry`		required	You should provide the country in ISO-2 format (e.g. NL or US)
`fromZipcode`		optional	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
`fromCity`		optional	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
`toCountry`		required	You should provide the country in ISO-2 format (e.g. NL or US)
`toZipcode`		optional	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.
`toCity`		optional	Please note, that if you don't provide a zipcode or city, we use the capital to calculate the estimate.

Example Body

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"
    }
  ]
}

Content item

Name	Value	Required	Comments
`description`	string	required	A clear description of the goods (e.g. "Cylinder head for compression-ignition diesel engine").
`numberOfItems`	integer	required	The number of units of this item in your shipment (e.g. 9).
`cost`	number	required	The value per item, stated in euros (€). This is used to calculate the customs value.
`tariff`	string	optional	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	optional	The country of origin of the goods in ISO-2 format (e.g. NL).

Example content item

JSON

{
  "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"
        }
    ]
}

{
  "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

JSON

{
  "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"
}

Estimate duties/taxes

Example request

#Header

#Body

#Example Body

#Content item

#Example content item

#Response

#Examples

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

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

Header

Body

Example Body

Content item

Example content item

Response

Examples

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

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