# Compare shipping options

> Get shipping rates from ParcelParcel

`POST https://services.parcelparcel.com/partners-api/v1/rates`

This endpoint allows you to return our shipping options based on a couple of parameters. We return the price (based on your own ParcelParcel account) per shipping option and the corresponding transit time.

See the [examples](#examples) for complete requests and responses.

## 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                                                                                                                                                                                                                      |
| :------------ | :-------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| parcels       | (object array) [Parcel](#parcel-type) | true     | More information is below. Currently, you can compare shipping options for a document, parcel or pallet shipment.                                                                                                             |
| 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 shipping rate and transit time.                                                                                                 |
| fromCity      |                       | false    | Please note, that if you don't provide a zipcode or city, we use the capital to calculate the shipping rate and transit time.                                                                                                 |
| 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 shipping rate and transit time.                                                                                                 |
| toCity        |                       | false    | Please note, that if you don't provide a zipcode or city, we use the capital to calculate the shipping rate and transit time.                                                                                                 |
| insured       | (bool)                | false    | Use this element to state if you want to insure your shipment or not. Please note, if you set this element to *true*, you also need to specify the *totalValue* element since it's required to calculate the insurance costs. |
| totalValue    | number                | false    | Define the total value of your shipment in euros (€). This is needed to calculate the insurance costs.                                                                                                                        |
| recipientType |                       | false    | The value is either *individual* or *business*. This value is required when you specify the type as *PALLET*.                                                                                                                 |

### Example Body

```json
{
  "parcels": [
    {
      "type": "NONDOC",
      "weight": "1.5",
      "height": "10",
      "width": "10",
      "length": "10",
      "count": "1"
    }
  ],
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "US",
  "toZipcode": "10001",
  "toCity": "New York",
  "insured": true,
  "totalValue": 100
}
```

### Parcel type

| Name      | Value               | Required | Comments                                                                                                                                                                   |
| :-------- | :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type      | NONDOC, DOC, PALLET | true     | You should choose *NONDOC* if you're shipping a parcel. *DOC* for a document shipment and *PALLET* for a pallet. It's not possible to combine multiple types of shipments. |
| weight    | 1 decimal           | true     | For example "10" or "15.2". Please note, that the weight is only required for *NONDOC* and *PALLET* shipments. This value should be stated in kilograms (kg).              |
| length    | integer             | true     | For example "40". Please note, that the length is only required for *NONDOC* and *PALLET* shipments. This value should be stated in centimetres (cm).                      |
| width     | integer             | true     | For example "30". Please note, that the width is only required for *NONDOC* and *PALLET* shipments. This value should be stated in centimetres (cm).                       |
| height    | integer             | true     | For example "20". Please note, that the height is only required for *NONDOC* and *PALLET* shipments. This value should be stated in centimetres (cm).                      |
| count     | integer             | true     | For example "1". Please note, that the count is required for *DOC*, *NONDOC* and *PALLET* shipments.                                                                       |
| stackable | (bool)              | true     | This is only needed when your *type* is equal to *PALLET*.                                                                                                                 |

#### Example NONDOC (Parcel):

```json
{
  "type": "NONDOC",
  "weight": "8.3",
  "height": "21",
  "width": "25",
  "length": "65",
  "count": "1"
}
```

#### Example DOC (Document):

```json
{
  "type": "DOC",
  "count": "1"
}
```

#### Example PALLET (Pallet shipment):

```json
{
  "type": "PALLET",
  "weight": "80",
  "height": "120",
  "width": "120",
  "length": "100",
  "count": "1",
  "stackable": false
}
```

## Response

The following response elements are returned:

| Name | Value | Comments |
| :--- | :--- | :--- |
| carrier | string | The carrier of the shipping option. Currently, we offer shipping options from the following carriers: FedEx DHL, TNT, DPD, DSV and Skynet. |
| product | string | The type of product (e.g. FedEx Economy or FedEx Priority) |
| price | number | The price is returned in euros (€), without VAT and with 2 decimals (e.g. 20.20). If you set the insurance to true, we also include the insurance costs in this price.<br>Please note, that some surcharges (e.g. *the remote area surcharge*) depend on the zip code/city of the pick-up and/or destination address. You can read more information about surcharges [on this page](https://www.parcelparcel.com/nl_NL/surcharge-information/). |
| minEstimatedTransitTimeInWorkingsDays | integer | The minimum estimated transit time of a shipping option is in working days. |
| maxEstimatedTransitTimeInWorkingsDays | integer | The maximum estimated transit time of a shipping option is in working days. |
| productId | number | You can use the *productId* if you want to [create a draft shipment](https://www.parcelparcel.com/api-docs/create-shipment/) with a specific shipping option. You can do this with the *preferredShippingOption* element (/draft endpoint). |
| priceBreakdown | array | This is a breakdown of how the price is built up. |
| priceBreakdown.item | string | This is an item of the price breakdown. |
| priceBreakdown.amount | number | This is the amount of the item in the price breakdown. |
| priceBreakdown.reason | string | For surcharges, we add the reason why a surcharge is applied. |

Please note, that we always return the cheapest option first in the response.

## Examples

Below, we have created multiple examples 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 - Get shipping options for a parcel shipment from the Netherlands to the United States

```bash cURL
curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/rates' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "parcels": [
    {
      "type": "NONDOC",
      "weight": "1.5",
      "height": "10",
      "width": "10",
      "length": "10",
      "count": "1"
    }
  ],
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "US",
  "toZipcode": "10001",
  "toCity": "New York",
  "insured": true,
  "totalValue": 100
}'
```
```http HTTP
POST /partners-api/v1/rates HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

{
  "parcels": [
    {
      "type": "NONDOC",
      "weight": "1.5",
      "height": "10",
      "width": "10",
      "length": "10",
      "count": "1"
    }
  ],
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "US",
  "toZipcode": "10001",
  "toCity": "New York",
  "insured": true,
  "totalValue": 100
}
```

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 - Get shipping options for a parcel shipment from the Netherlands to the United States

```json
{
  "errors": false,
  "message": "Rates successfully processed",
  "data": [
    {
      "carrier": "DHL",
      "product": "DHL Express Worldwide",
      "productId": 74,
      "price": 84.08,
      "minEstimatedTransitTimeInWorkingsDays": 6,
      "maxEstimatedTransitTimeInWorkingsDays": 7,
      "priceBreakdown": [
        {
          "item": "DHL Express Worldwide",
          "amount": 84.08
        }
      ]
    },
    {
      "carrier": "FedEx",
      "product": "FedEx Economy",
      "productId": 79,
      "price": 90,
      "minEstimatedTransitTimeInWorkingsDays": 8,
      "maxEstimatedTransitTimeInWorkingsDays": 9,
      "priceBreakdown": [
        {
          "item": "FedEx Economy",
          "amount": 90
        }
      ]
    },
    {
      "carrier": "FedEx",
      "product": "FedEx Priority",
      "productId": 80,
      "price": 94.36,
      "minEstimatedTransitTimeInWorkingsDays": 3,
      "maxEstimatedTransitTimeInWorkingsDays": 4,
      "priceBreakdown": [
        {
          "item": "FedEx Priority",
          "amount": 94.36
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express 12:00",
      "productId": 78,
      "price": 112.88,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "DHL Express 12:00",
          "amount": 112.88
        }
      ]
    },
    {
      "carrier": "TNT",
      "product": "TNT Express",
      "productId": 95,
      "price": 130.55,
      "minEstimatedTransitTimeInWorkingsDays": 6,
      "maxEstimatedTransitTimeInWorkingsDays": 7,
      "priceBreakdown": [
        {
          "item": "TNT Express",
          "amount": 130.55
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express 10:30",
      "productId": 113,
      "price": 134.54,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "DHL Express 10:30",
          "amount": 134.54
        }
      ]
    }
  ]
}
```

### Request example - Get shipping options for a document shipment from the Netherlands to the United States

```bash cURL
curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/rates' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "parcels": [
    {
      "type": "DOC",
      "count": "1"
    }
  ],
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "US",
  "toZipcode": "10001",
  "toCity": "New York",
  "insured": false,
  "totalValue": 100
}'
```
```http HTTP
POST /partners-api/v1/rates HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

{
  "parcels": [
    {
      "type": "DOC",
      "count": "1"
    }
  ],
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "US",
  "toZipcode": "10001",
  "toCity": "New York",
  "insured": false,
  "totalValue": 100
}
```

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 - Get shipping options for a document shipment from the Netherlands to the United States

```json
{
  "errors": false,
  "message": "Rates successfully processed",
  "data": [
    {
      "carrier": "DHL",
      "product": "DHL Express 12:00",
      "productId": 78,
      "price": 55.27,
      "minEstimatedTransitTimeInWorkingsDays": 7,
      "maxEstimatedTransitTimeInWorkingsDays": 8,
      "priceBreakdown": [
        {
          "item": "DHL Express 12:00",
          "amount": 55.27
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express Worldwide",
      "productId": 74,
      "price": 59.98,
      "minEstimatedTransitTimeInWorkingsDays": 7,
      "maxEstimatedTransitTimeInWorkingsDays": 8,
      "priceBreakdown": [
        {
          "item": "DHL Express Worldwide",
          "amount": 59.98
        }
      ]
    },
    {
      "carrier": "FedEx",
      "product": "FedEx Priority",
      "productId": 80,
      "price": 65.61,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "FedEx Priority",
          "amount": 65.61
        }
      ]
    },
    {
      "carrier": "TNT",
      "product": "TNT Express",
      "productId": 95,
      "price": 66.68,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "TNT Express",
          "amount": 66.68
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express 10:30",
      "productId": 113,
      "price": 68.06,
      "minEstimatedTransitTimeInWorkingsDays": 7,
      "maxEstimatedTransitTimeInWorkingsDays": 8,
      "priceBreakdown": [
        {
          "item": "DHL Express 10:30",
          "amount": 68.06
        }
      ]
    }
  ]
}
```

### Request example - Get shipping options for a pallet shipment from the Netherlands to the United States

```bash cURL
curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/rates' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "parcels": [
    {
      "type": "PALLET",
      "weight": "80",
      "height": "120",
      "width": "120",
      "length": "100",
      "count": "1",
      "stackable": false
    }
  ],
  "recipientType": "business",
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "NL",
  "toZipcode": "1052LP",
  "toCity": "Amsterdam",
  "insured": false,
  "totalValue": 100
}'
```
```http HTTP
POST /partners-api/v1/rates HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

{
  "parcels": [
    {
      "type": "PALLET",
      "weight": "80",
      "height": "120",
      "width": "120",
      "length": "100",
      "count": "1",
      "stackable": false
    }
  ],
  "recipientType": "business",
  "fromCountry": "NL",
  "fromZipcode": "1411 AT",
  "fromCity": "Naarden",
  "toCountry": "NL",
  "toZipcode": "1052LP",
  "toCity": "Amsterdam",
  "insured": false,
  "totalValue": 100
}
```

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 - Get shipping options for a pallet shipment within the Netherlands (domestic)

```json
{
  "errors": false,
  "message": "Rates successfully processed",
  "data": [
    {
      "carrier": "DSV",
      "product": "DSV Road Domestic",
      "productId": 114,
      "price": 67.05,
      "minEstimatedTransitTimeInWorkingsDays": 1,
      "maxEstimatedTransitTimeInWorkingsDays": 2,
      "priceBreakdown": [
        {
          "item": "DSV Road Domestic",
          "amount": 67.05
        }
      ]
    },
    {
      "carrier": "TNT",
      "product": "TNT Express domestic",
      "productId": 102,
      "price": 300.02,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "TNT Express domestic",
          "amount": 300.02
        }
      ]
    },
    {
      "carrier": "TNT",
      "product": "TNT Domestic 12:00",
      "productId": 103,
      "price": 312.51,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "TNT Domestic 12:00",
          "amount": 312.51
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express Domestic",
      "productId": 105,
      "price": 948.58,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "DHL Express Domestic",
          "amount": 948.58
        }
      ]
    },
    {
      "carrier": "DHL",
      "product": "DHL Express 12:00",
      "productId": 78,
      "price": 1156.87,
      "minEstimatedTransitTimeInWorkingsDays": 5,
      "maxEstimatedTransitTimeInWorkingsDays": 6,
      "priceBreakdown": [
        {
          "item": "DHL Express 12:00",
          "amount": 1156.87
        }
      ]
    }
  ]
}
```