# Estimate duties/taxes

> Estimate the import duties and taxes of a shipment.

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

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](#examples) for a complete request and response. Not sure if a shipment goes through customs at all? [Check the route](https://www.parcelparcel.com/api-docs/dutiable-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`.

## 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](https://www.parcelparcel.com/api-docs/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](#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

```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  | 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:

```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](https://www.parcelparcel.com/api-docs/postman-guide/).

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

```bash cURL
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"
    }
  ]
}'
```
```http HTTP
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](https://www.parcelparcel.com/api-docs/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"
}
```