Compare shipping options

Markdown

Get shipping rates from ParcelParcel

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

Example request

Get shipping options for a parcel shipment from the Netherlands to the United States More examples

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

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

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

import requests

response = requests.post(
    "https://services.parcelparcel.com/partners-api/v1/rates",
    headers={
        "X-PP-API": "{YourAPIKey}@{YourAPISecret}",
        "Content-Type": "application/json",
    },
    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,
    },
)
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 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 for complete requests and responses.

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	required	More information is below. Currently, you can compare shipping options for a document, parcel or pallet shipment.
`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 shipping rate and transit time.
`fromCity`		optional	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`		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 shipping rate and transit time.
`toCity`		optional	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)	optional	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	optional	Define the total value of your shipment in euros (€). This is needed to calculate the insurance costs.
`recipientType`		optional	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	required	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	required	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	required	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	required	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	required	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	required	For example "1". Please note, that the count is required for DOC, NONDOC and PALLET shipments.
`stackable`	(bool)	required	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. 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`	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 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
}

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

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

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
}

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

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

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
}

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

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

Compare shipping options

Example request

#Header

#Body

#Example Body

#Parcel type

#Example NONDOC (Parcel)

#Example DOC (Document)

#Example PALLET (Pallet shipment)

#Response

#Examples

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

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

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

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

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

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

Header

Body

Example Body

Parcel type

Example NONDOC (Parcel)

Example DOC (Document)

Example PALLET (Pallet shipment)

Response

Examples

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

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

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

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

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

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