🚚 Compare shipping options

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

If you successfully made a request to compare our shipping options, it will look something like this:

Method

In order to create a draft shipment, you need to use the following method:

POST

Endpoint

You need the following endpoint:

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

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
parcels	(object array) Parcel	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		true	The value is either individual or business. This value is required when you specify the type as PALLET.

Example Body

{
    "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.
length	integer	true	For example "40". Please note, that the length is only required for NONDOC and PALLET shipments.
width	integer	true	For example "30". Please note, that the width is only required for NONDOC and PALLET shipments.
height	integer	true	For example "20". Please note, that the height is only required for NONDOC and PALLET shipments.
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 required when your type is equal to PALLET.

Example NONDOC (Parcel):

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

Example DOC (Document):

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

Example PALLET (Pallet shipment):

        {
            "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	string	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. 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.
minEstimatedTransitTimeInWorkingsDays	number	The minimum estimated transit time of a shipping option is in working days.
maxEstimatedTransitTimeInWorkingsDays	number	The maximum estimated transit time of a shipping option is in working days.
productId	string	You can use the productId if you want to create a draft 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.

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

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
}'

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

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

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

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
}'

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
}

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

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

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

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
}'

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
}

Response example - Get shipping options for a pallet shipment within the Netherlands (domestic)

{
    "errors": false,
    "message": "Rates successfully processed",
    "data": [
        {
            "carrier": "DSV",
            "product": "DSV Road Domestic",
            "productId": 114,
            "price": 67.05,
            "estimatedTransitTimeInWorkingDays": 1
        },
        {
            "carrier": "TNT",
            "product": "TNT Express domestic",
            "productId": 102,
            "price": 300.02,
            "estimatedTransitTimeInWorkingDays": 5
        },
        {
            "carrier": "TNT",
            "product": "TNT Domestic 12:00",
            "productId": 103,
            "price": 312.51,
            "estimatedTransitTimeInWorkingDays": 5
        },
        {
            "carrier": "DHL",
            "product": "DHL Express Domestic",
            "productId": 105,
            "price": 948.58,
            "estimatedTransitTimeInWorkingDays": 5
        },
        {
            "carrier": "DHL",
            "product": "DHL Express 12:00",
            "productId": 78,
            "price": 1156.87,
            "estimatedTransitTimeInWorkingDays": 5
        }
    ]
}