Documentation

Checkout webservice

Summary

  • Name: Checkout Webservice.
  • Reason to Call: Receive information regarding delivery options. 
  • Input: Details of dates, address of the customer, order date and delivery options. 
  • Output: Timeframes and pickup locations.

Method

REST (Get) Description
/v1/checkoutReturns timeframes and/or locations depending on the request input

Call details

Interface version V1*
Sandbox endpointhttps://api-sandbox.postnl.nl/shipment/v1/checkout
Sandbox swaggerhttps://api-sandbox.postnl.nl/shipment/v1/checkout/swagger.json
Production endpointhttps://api.postnl.nl/shipment/v1/checkout
Production swaggerhttps://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.

Delivery options
It is possible to specify which delivery options should be considered. Here are the possible values:

OptionDescription
DaytimeDaytime delivery
EveningEvening delivery
SundaySunday delivery
SamedaySameday delivery
DeliveryOnDemandMytime delivery (In Dutch: Op Afspraak bezorgd)
08:00-10:00Guaranteed delivery between the timeframe specified
08:00-12:00Guaranteed delivery between the timeframe specified
08:00-17:00Guaranteed delivery between the timeframe specified
08:00-09:00Guaranteed delivery between the timeframe specified
09:00-12:00Guaranteed delivery between the timeframe specified
09:00-16:00Guaranteed delivery between the timeframe specified
12:00-17:00Guaranteed delivery between the timeframe specified
PickupPickup at PostNL location
EarlyMorningPickupEarly morning pickup (before 10:00)

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 and Sunday. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager. For Sunday delivery it is even mandatory to consult your account manager. 

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

Request

/v1/checkout

ParameterMandatoryFormatDescriptionExample
ApikeyMString [32] Authenticate using your API key. R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX
OrderDateMString[19] The order date of the shipment11-07-2019 12:34:54
ShippingDurationOString [2] The amount of days it takes for a parcel to be received by PostN. If you delivery the parcel the same day as the order is placed on the webshop, please use the value of 1. A value of 2 means the parcel will arrive at PostNL a day later etc.1
CutOffTimesMString [2] Array of CutOffTimes Type
HolidaySortingOBoolean Specifies whether you are available during holidays 
OptionsMArray of stringSpecifies the delivery and pickup options, for a list of possible values please refer to the guidelinesDaytime
LocationsMInteger [2]Specifies the number of locations you want returned. This can be a value of 1-33
DaysMInteger [2] Specifies the number of days for which the timeframes are returned. This can be a value of 1-55
AddressesMArrayArray of Address type

CutOffTimes type

ParameterMandatoryFormatDescriptionExample
DayMString [2] The day for which the cutoff time applies. The following values can be used:
00: default
01: Monday
02: Tuesday
07: Sunday
00
AvailableOBoolean Specifies whether you are available to process shipments during the selected day.true
TimeO-MString [8] Specifies the cutoff time (mandatory when Available is true)23:00:00
Type0String [0-10] Specifies the type belonging to the cutoff time. Possible values:
Regular and Sameday
Regular



Address type

ParameterMandatoryFormatDescriptionExample
AddressTypeMString [2] Address type. Possible values are:
01: receiver address
02: sender address
01


StreetOString[0-35] Street name; for Belgian addresses, it is strongly recommended to fill in the  street valueSiriusdreef
HouseNrMInteger [1-5] The house number of the delivery address42
HouseNrExtOString [0-7] House number extensionA
ZipcodeMString [4-6]Zipcode of the address2132WT
CityOString [0-35]City of the address Hoofddorp
CountrycodeMString[2]ISO2 country codeNL

Example

curl -X POST "https://api-sandbox.postnl.nl/shipment/v1/checkout"
-H "accept: application/json" -H "apikey: R6bZsmPGjaQUlOKPOXyQOEQlJzSTykdX” 

Request body: 
{
    "OrderDate": "07-07-2019 12:34:54",
    "ShippingDuration": 1,
    "CutOffTimes": [{
            "Day": "00",
            "Available": true,
            "Type": "Regular",
            "Time": "23:00:00"
        }, {
            "Day": "07",
            "Available": false,
            "Type": "Regular"
        }
    ],
    "HolidaySorting": true,
    "Options": ["Daytime", "Evening", "Pickup"],
    "Locations": 1,
    "Days": 3,
    "Addresses": [{
            "AddressType": "01",
            "Street": "Molengraaffplantsoen",
            "HouseNr": "74",
            "HouseNrExt": "bis",
            "Zipcode": "3571ZZ",
            "City": "Utrecht",
            "Countrycode": "NL"
        }, {
            "AddressType": "02",
            "Countrycode": "NL"
        }
    ]
}

Response Checkout service

Parameter  DescriptionExample
DeliveryOptions  Array of DeliveryOption type
PickupOptions  Array of PickupOption type
Warnings  Array of Warning type

DeliveryOption type

Parameter  DescriptionExample
Deliverydate  String09-07-2019
Timeframe  Array of Timeframe type

Timeframe type

Parameter  DescriptionExample
Options  The delivery options applicable to the timeframe information. Evening
ShippingDate  The date when you need to deliver the shipment to PostNL to ensure the expected delivery date is achieved08-07-2019
From   Format hh:mm:ss18:00:00
Options  The delivery options applicable to the timeframe information. See Guidelines for possible values.Evening
To   Format hh:mm:ss21:30:00

PickupOptions type

Attribute  DescriptionExample
PickupDate  Date from which the parcel can be picked up at the PostNL location09-07-2019
ShippingDate  The date when you need to deliver the shipment to PostNL to ensure the expected delivery date is achieved08-07-2019
Option  The pickup option
Pickup at PostNL locations. 
Pickup
Locations  Array of Location type

Location type

Parameter  DescriptionExample
Address  Address type 
PickupTime  Time from when the parcel can be retrieved at the pickup location15:00
OpeningHours  OpeningHours type
Distance  The calculated distance (in meters) between the location specified and the address provided in the request138
LocationCode  The location identifier8101163043
PartnerID  The partner identifierPNPNL-01

OpeningHours type

ParameterDescriptionExample
MondayOpeningHour type
TuesdayOpeningHour type
WednesdayOpeningHour type
ThursdayOpeningHour type
FridayOpeningHour type
SaturdayOpeningHour type
SundayOpeningHour type


OpeningHours type

ParameterDescriptionExample
FromStart time09:00:00
CodeWarning code (for a possible list of warnins, see the generic error codes page)18:00:00

Warning type

ParameterDescriptionExample
DeliveryDateDeliverydate that triggered the warning07-07-2019
CodeWarning code (for a possible list of warnins, see the generic error codes page)03
DescriptionWarning description (for a possible list of warnings, see the generic error codes page)Dag uitgesloten van tijdvak
OptionsArray of options. Delivery option that triggered the warningDaytime

Example

{
    "DeliveryOptions": [{
            "DeliveryDate": "09-07-2019",
            "Timeframe": [{
                    "From": "13:45:00",
                    "To": "16:15:00",
                    "Options": ["Daytime"],
                    "ShippingDate": null
                }, {
                    "From": "18:00:00",
                    "To": "22:00:00",
                    "Options": ["Evening"],
                    "ShippingDate": null
                }
            ]
        }, {
            "DeliveryDate": "10-07-2019",
            "Timeframe": [{
                    "From": "14:00:00",
                    "To": "16:30:00",
                    "Options": ["Daytime"],
                    "ShippingDate": null
                }, {
                    "From": "18:00:00",
                    "To": "22:00:00",
                    "Options": ["Evening"],
                    "ShippingDate": null
                }
            ]
        }
    ],
    "PickupOptions": [{
            "PickupDate": "09-07-2019",
            "ShippingDate": null,
            "Option": "Pickup",
            "Locations": [{
                    "Address": {
                        "Street": "Jan van Galenstraat",
                        "Zipcode": "3572LD",
                        "HouseNr": 93,
                        "HouseNrExt": "",
                        "Countrycode": "NL",
                        "CompanyName": "Tabakszaak Vroon"
                    },
                    "PickupTime": "15:00",
                    "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"
                        }
                    },
                    "Distance": 138,
                    "LocationCode": "8101163043",
                    "PartnerID": "PNPNL-01"
                }, {
                    "Address": {
                        "Street": "Troosterhof",
                        "Zipcode": "3571NC",
                        "HouseNr": 7,
                        "HouseNrExt": "",
                        "Countrycode": "NL",
                        "CompanyName": "Primera"
                    },
                    "PickupTime": "15:00",
                    "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"
                        }
                    },
                    "Distance": 390,
                    "LocationCode": "6693112498",
                    "PartnerID": "PNPNL-01"
                }
            ]
        }
    ],
    "Warnings": [{
            "DeliveryDate": "07-07-2019",
            "Code": "03",
            "Description": "Dag uitgesloten van tijdvak",
            "Options": ["Daytime"]
        }, {
            "DeliveryDate": "07-07-2019",
            "Code": "03",
            "Description": "Dag uitgesloten van tijdvak",
            "Options": ["Evening"]
        }, {
            "DeliveryDate": "08-07-2019",
            "Code": "08",
            "Description": "Geen bezorgopties gevonden op datum.",
            "Options": ["Daytime"]
        }, {
            "DeliveryDate": "08-07-2019",
            "Code": "08",
            "Description": "Geen bezorgopties gevonden op datum.",
            "Options": ["Evening"]
        }
    ]
}