The Checkout API combines the functionality of the DeliveryDate, Location and Timeframe API’s. So you only need 1 API for showing all PostNL delivery options in your checkout. In this way it becomes easier to implement the delivery options and there is also less overhead in requesting the PostNL services by using this 3-in-1 API.
Why use the Checkout API?
Delivery options
This API provides the possible day(s) of delivery, timeframes and PostNL pickup locations to display in the checkout of a webshop. Based on the address of the customer, orderdate and specified delivery options, you get timeframes and nearest PostNL pickup locations in the response.
Customers convenience
Enhance your customer's online shopping experience by providing more control over the delivery of their purchased product. Integrate the PostNL frontend webservices into your checkout and empower your customers to choose the delivery option that suits them best.
More information and control
Using the Checkout API gives your customers more information and control about the arrival of the parcels. But it is good to realize that it gives you, the webshop, also a responsibility to deliver the parcel on time by PostNL.
Get started
Request your (Sandbox) API Key and start using the API.
As soon as you have an API key, it is recommended to run our Postman collections. Here you can find code examples of the various services and products we offer. This makes implementing the APIs much easier.
Development
On this page you will find all the necessary information for implementing this API.
Please check the Guidelines for useful information.
Descriptions, formats and examples of the API attributes are also very useful to look at.
Method
Method: POST
Path | Description |
v1/checkout | Returns timeframes and/or locations depending on the request input. |
Call details
| Interface version | V1* |
| Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v1/checkout |
| Sandbox swagger | https://api-sandbox.postnl.nl/shipment/v1/checkout/swagger.json |
| Production endpoint | https://api.postnl.nl/shipment/v1/checkout |
| Production swagger | https://api.postnl.nl/shipment/v1/checkout/swagger.json |
*This API combines the functionality of the DeliveryDate, Location and Timeframe webservices.
Versioning
REST:
API
| Version | Release Date | Status | Release Notes | Schema Changes |
Checkout | 1 | Jul 05, 2019 | Current version | First version | N/A |
Guidelines
Use of the webservice
This API can be used to fill a webshop’s checkout page.
Sundays and public holidays
This service takes into account ‘non-business’ days like Sundays and public holidays.
Holiday sorting
It is possible to allow for holiday sorting. With holiday sorting enabled, you can tell PostNL that you will be able to deliver the parcel to PostNL during holidays.
Sustainability options
You can show customers when their parcel can be delivered sustainably. In the response of the API the follow sustainability codes be distinguished:
Code 01 = Sustainable delivery
Code 02 = Sustainable option
Code 03 = Sustainable delivery + Sustainable option
Code 00 - Not available
You can build in the corresponding communication messages in your checkout;
Sustainably delivery; “Duurzaam bezorgd”
Sustainable option; “Duurzame optie”
Not available: Not a sustainable option (yet).
Sustainably delivery
1. PostNL delivers the parcel to your address with an electric vehicle or with a sustainable fuel vehicle.
2. PostNL delivers the parcel to a PostNL location with an electric vehicle or with a sustainable fuel vehicle.
Sustainable option
If we can deliver the package at a PostNL retail location or in a parcel machine we deliver fewer kilometers. We can also deliver multiple parcels at 1 (retail) point. This results in less CO2 emissions.
In the below file you can find the visual assets which you can you use in your checkout to show the sustainability options.
Visual assets
Delivery options
It is possible to specify which delivery options should be considered. The possible values are:
| Option | Description |
| Daytime | Daytime delivery |
| Evening | Evening delivery |
| Sunday | Sunday delivery |
| Today | Delivery on day of handover to PostNL |
| Sameday | Sameday delivery |
| 08:00-09:00 | Guaranteed delivery between the timeframe specified |
| 08:00-10:00 | Guaranteed delivery between the timeframe specified |
| 08:00-12:00 | Guaranteed delivery between the timeframe specified |
| 08:00-17:00 | Guaranteed delivery between the timeframe specified |
| Pickup | Pickup at PostNL location |
All the above delivery options can be used in the request of the Checkout API. PostNL will charge an additional amount for delivery of the parcels with the options Evening, Morning, (After)Noon, Sameday, Delivery on demand, Guaranteed delivery, Sunday and Today. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager. For Sunday, Sameday and Today delivery it is even mandatory to consult your account manager.
* The Today delivery option will be returned on any given day (Mon – Sun), but will only be on the first following business day.
Vissual Assets
The Visual Assets can be useful to create a delivery options frame in your checkout.
Warnings
Warnings are returned when there is a functional problem with the request (e.g. when an address is not recognized, or when no delivery options are available).
Error codes
Error codes have been specified in the below PDF file. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.
Checkout_Error_Codes
Example
curl --location --request POST
'https://api-sandbox.postnl.nl/shipment/v1/checkout' \
--header 'apikey: ***' \
--header 'Content-Type: application/json' \
--data-raw '{
"OrderDate": "04-09-2022 12:00:00",
"ShippingDuration": "1",
"CutOffTimes": [
{
"Day": "00",
"Available": "true",
"Type": "regular",
"Time": "20:00:00"
}
],
"HolidaySorting": "true",
"Options": [
"Daytime",
"Pickup"
],
"Locations": "3",
"Days": "5",
"Addresses": [
{
"AddressType": "01",
"Street": "Molengraaffplantsoen",
"HouseNr": "74",
"HouseNrExt": "",
"Zipcode": "3571ZZ",
"City": "Utrecht",
"Countrycode": "NL"
}
]
}'
Response:
{
"DeliveryOptions": [
{
"DeliveryDate": "05-09-2022",
"Timeframe": [
{
"From": "10:30:00",
"To": "13:00:00",
"Options": [
"Daytime"
],
"ShippingDate": null
}
]
},
{
"DeliveryDate": "06-09-2022",
"Timeframe": [
{
"From": "12:15:00",
"To": "14:45:00",
"Options": [
"Daytime"
],
"ShippingDate": null
}
]
},
{
"DeliveryDate": "07-09-2022",
"Timeframe": [
{
"From": "12:00:00",
"To": "14:30:00",
"Options": [
"Daytime"
],
"ShippingDate": null
}
]
},
{
"DeliveryDate": "08-09-2022",
"Timeframe": [
{
"From": "11:30:00",
"To": "14:00:00",
"Options": [
"Daytime"
],
"ShippingDate": null
}
]
},
{
"DeliveryDate": "09-09-2022",
"Timeframe": [
{
"From": "11:15:00",
"To": "13:45:00",
"Options": [
"Daytime"
],
"ShippingDate": null
}
]
}
],
"PickupOptions": [
{
"PickupDate": "05-09-2022",
"Option": "Pickup",
"Locations": [
{
"PartnerID": "PNPNL-01",
"LocationCode": "163043",
"Address": {
"CompanyName": "Tabakszaak Vroon",
"Street": "Jan van Galenstraat",
"HouseNr": 93,
"HouseNrExt": "",
"Zipcode": "3572LD",
"City": "Utrecht",
"Countrycode": "NL"
},
"PickupTime": "15:00",
"Distance": 138,
"OpeningHours": {
"Monday": {
"From": "08:00:00",
"To": "18:00:00"
},
"Tuesday": {
"From": "08:00:00",
"To": "18:00:00"
},
"Wednesday": {
"From": "08:00:00",
"To": "18:00:00"
},
"Thursday": {
"From": "08:00:00",
"To": "18:00:00"
},
"Friday": {
"From": "08:00:00",
"To": "18:00:00"
},
"Saturday": {
"From": "08:00:00",
"To": "17:00:00"
}
}
},
{
"PartnerID": "PNPNL-01",
"LocationCode": "214646",
"Address": {
"CompanyName": "Primera",
"Street": "Troosterhof",
"HouseNr": 12,
"HouseNrExt": "",
"Zipcode": "3571NC",
"City": "Utrecht",
"Countrycode": "NL"
},
"PickupTime": "15:00",
"Distance": 400,
"OpeningHours": {
"Monday": {
"From": "08:30:00",
"To": "18:00:00"
},
"Tuesday": {
"From": "08:30:00",
"To": "18:00:00"
},
"Wednesday": {
"From": "08:30:00",
"To": "18:00:00"
},
"Thursday": {
"From": "08:30:00",
"To": "18:00:00"
},
"Friday": {
"From": "08:30:00",
"To": "18:00:00"
},
"Saturday": {
"From": "08:30:00",
"To": "17:00:00"
}
}
},
{
"PartnerID": "PNPNL-01",
"LocationCode": "220852",
"Address": {
"CompanyName": "030 fietsen",
"Street": "Nobelstraat",
"HouseNr": 3,
"HouseNrExt": "",
"Zipcode": "3512EK",
"City": "UTRECHT",
"Countrycode": "NL"
},
"PickupTime": "15:00",
"Distance": 1481,
"OpeningHours": {
"Monday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Tuesday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Wednesday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Thursday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Friday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Saturday": {
"From": "09:00:00",
"To": "18:00:00"
},
"Sunday": {
"From": "10:00:00",
"To": "17:00:00"
}
}
}
]
},
{
"PickupDate": "05-09-2022",
"Option": "ParcelMachine",
"Locations": []
}
],
"Warnings": [
{
"DeliveryDate": "04-09-2022",
"Code": "5034",
"Description": "No delivery option found on date",
"Options": [
"Daytime"
]
}
]
}
