Deliverydate

Documentation

With this API you can determine the first date customers can receive their parcels. And it is also possible to determine the date you need to supply the parcels to PostNL in order to have the parcels delivered to your customers on a given shipping date.

Why use the Deliverydate API

• Use this service as a starting point in the Timeframe API to show customers the possible day and time of arrival.

• PostNL delivery days and dates are always up to date by using this service and takes into account ‘non-business’ days like Sundays and public holidays.

• This API contains two methods; it calculates the expected delivery date for shipment and can calculates the date to handover or send the shipments.

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 collectio ns. Here you can find code examples of the various services and products we offer. This makes implementing the APIs much easier.

Start using the API
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.

Methods

Method: GET
Path
Description
/calculate/date/delivery
Calculates the expected delivery date for a shipment based on the retrieved parameters.
/calculate/date/shipping
Calculates the date to send the shipment based on the retrieved parameters.

Call details

Interface version 2_2
Sandbox endpoint https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date
Sandbox wsdl https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date/soap.wsdl
Sandbox swagger https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date/swagger.json
Production endpoint https://api.postnl.nl/shipment/v2_2/calculate/date
Production wsdl https://api.postnl.nl/shipment/v2_2/calculate/date/soap.wsdl
Production swagger https://api.postnl.nl/shipment/v2_2/calculate/date/swagger.json

Versioning

REST:
API

Version
Release Date
Status
Release Notes
Schema Changes
DeliveryDate
2_2
Jun 01, 2017
Current version
IN COMPARISON TO THE 2_1 SOAP VERSION,
the following fields have been added to the interface:
OriginCountryCode
CutoffTime.Available.
New delivery option: MyTime (Delivery on demand)
PRODUCT NO LONGER EXISTS
N/A

SOAP:

API
Version
Release Date
Status
Release Notes
Schema Changes
DeliveryDate
1_0
Oct 7, 2013
Not supported

1_1
Jan 24, 2014
Not supported
Different namespaces
New additional method (GetSentDate)
Yes
1_2
Aug 14, 2014
Not supported
Different namespaces
Yes
2_0
Aug 14, 2015
Not supported
CutOffTime and CutOffTimeForSundaySorting replaced by CutOffTimes list
In the previous version of the GetDeliveryDate method, cut off times were specified for weekdays and Sunday in two fields. It is now possible to specify cut off times for every day of the week in the new CutOffTimes field.
To replicate the old functionality in the new message format, replace the CutOffTime field by a CutOffTime in the CutOffTimes list with Day value 00 and replace the CutOffTimeForSundaySorting field by a CutOffTime in the CutOffTimes list with Day value 07.
Options field added
It is now possible to specify which delivery options should be considered when returning a delivery or sent date using the new Options field. The GetDeliveryDate method will also specify which delivery option is applicable to the returned delivery date in the new Option field. See the interface specification for more details on the available delivery options. The new Options field is mandatory. To replicate the old 1_2 functionality, specify delivery option Daytime.
New and updated address fields
Several address fields have been added to the GetDeliveryDate and GetSendDate elements to specify the delivery address more precisely. These fields are: Street, HouseNrExt, City and CountryCode. CountryCode is a mandatory field. For an address in the Netherlands, specify NL for this field. In 1_2, the PostalCode field was only mandatory when AllowSundaySorting was set to true. It is always mandatory in 2_0. Furthermore, the HouseNumber field has been renamed to HouseNr.
Yes
2_1
Nov 03, 2015
Supported
GetDeliveryDateResponse. Option is removed from the interface.
GetDeliveryDateResponse. Options is added to the interface.
Yes
2_2
Aug 24, 2017
Current Version
The following fields have been added to the interface:
OriginCountryCode
CutoffTime.Available
New delivery option: MyTime (Delivery on demand)
PRODUCT NO LONGER EXISTS
Yes

GUIDELINES

Using the methods
Based on the (first possible) shipping date you can determine the appropriate delivery date by PostNL. The delivery date can be requested through the GetDeliveryDate method.
You can use the GetSentDate method to determine the date that you need to supply the parcel to PostNL in order to have the parcel delivered to your customer on the date supplied to this service.
You can use Shipping Duration to define a delay in shipping the parcels to a PostNL location. Shipping duration means the duration it takes from the moment the order is created up until delivery to PostNL.
A value of 1 means that you prepare and send the shipment on the same day. A value of 2 means that there is a day in-between preparing the shipment and the shipment arriving at a PostNL location etc.
Sundays and public holidays
This service takes into account ‘non-business’ days like Sundays and public holidays.
Sunday sorting
It is possible to allow for Sunday sorting. With Sunday sorting enabled, Monday will also be a valid delivery day. When using this option, make sure you have selected Monday delivery in your contract.
Delivery options (GetDeliveryDate)
It is possible to specify which delivery options should be considered when returning a deliverydate using the field Options. The GetDeliveryDate method will also specify which delivery option is applicable to the returned delivery date in the Option field.
Only one delivery option can be specified at once (with exception of Sameday in combination with Evening).
Options
Description
Daytime
Daytime delivery
Evening
Evening delivery
Morning
Morning delivery before 10:00
Noon
Morning delivery before 12:00
Today*
Delivery on day of handover to PostNL
Sunday
Sunday delivery
Sameday
Sameday delivery (must be used in combination with Evening)
Afternoon
Afternoon delivery before 17:00
* The Today delivery option will be returned on any given day (Mon – Sun), but will only be on the first following business day.
Delivery options (GetSentDate)
It is also possible to specify the above delivery options when returning a sentdate by using the Options field.

Note: the given Options will not effect the response; it is always processed as Daytime option.

Best practice
Integrate all three PostNL frontend webservices into your checkout and empower your customers to choose the delivery option that suits them best.

First use the Deliverydate webservice (Get deliverydate method) to determine the available and possible delivery date(s), based on your shipping date. Use the received date from this service as a starting point in the Timeframe webservice to show customers the possible day and time of arrival. In this way you avoid showing not possible deliverydates. The postal code that customers enter by placing their order, determine the timeframes that apply to their address.

Use the Location webservice to show the nearest pickup point(s) based on the postal code or coordinates of the customers. The location(s) can be shown in a map if you want to make it visually more appealing.
The Visual assets can be useful to create a delivery options frame in your checkout.
Error codes
Error codes ave 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 PostNL API.
Deliverydate_Error_Codes

Code examples

Request GetDeliveryDate: curl --location --request GET 'https://api-sandbox.postnl.nl/shipment/v2_2/calculate/ date/delivery?AllowSundaySorting=true&ShippingDuration=1& ShippingDate=01-092022& Options=Daytime&CutOffTime=17:00:00& OriginCountryCode=NL&CountryCode=NL&PostalCode=3532VC&HouseNumber=49& City=Utrecht&Street=Bilderdijkstraat' \ --header 'apikey: ***' \ Response: {     "DeliveryDate": "02-09-2022",     "Options": {         "string": "Daytime"     } } Request GetSentDate: curl --location --request GET 'https://api-sandbox.postnl.nl/shipment/v2_2/calculate/ date/shipping?ShippingDuration=1&DeliveryDate=02-09-2022&PostalCode=3532VC& CountryCode=NL&City=Utrecht&Street=Bilderdijkstraat&HouseNumber=49' \ --header 'apikey: ***' \ Response: {     "SentDate": "01-09-2022" }

Request GetDeliveryDate

GetDeliveryDate type

Attribute Mandatory Format Description Example
AllowSundaySorting M Boolean [true/false] Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday). true
City O String [0-35] City of the address   Hoofddorp
Countrycode M String [2] The ISO2 country codes NL
CutOffTimes M CutOffTime type Cut off times per day. At least one cut off time must be specified.
HouseNr O String [0-35] The house number of the delivery address 42
HouseNrExt O String [0-35] House number extension A
Options M String [7-9] The delivery options for which a delivery date
should be returned. Only one delivery option can
be specified. See Guidelines for possible values. Daytime
OriginCountryCode
O String [2] Origin country of the shipment
Default NL
Possible values NL and BE. NL
PostalCode M String [4-10] Zipcode of the address 2132WT
ShippingDate M Datetime [19] Date/time of preparing the shipment for sending. Format: dd-mm-yyyy hh:mm:ss 29-06-2016 14:00:00
ShippingDuration M Integer [1] The duration it takes for the shipment to be delivered to PostNL in days. A value of 1 means that the parcel will be delivered to PostNL on the same day as the date specified in ShippingDate. A value of 2 means the parcel will arrive at PostNL a day later etc. 1
Street O String [0-95] The street name of the delivery address. Siriusdreef

CutOffTime type

Attribute Mandatory Format Description Example
Day M Integer [2] Number of the day of week. 01 = Monday, 02 =
Tuesday, …, 07 = Sunday. It is also possible to use value 00 to specify a generic cut off time for all days. 00
Time M Time [8] The cut off time for this day of week.
Format: hh:mm:ss 14:00:00
Available O Boolean [true/false] Specifies whether you are available on the day entered in CutOffTime.Day. If you are closed on a Sunday for instance, this value is set to false for CutOffTime.Day = 07. true

Message type

Attribute Mandatory Format Description Example
MessageID M String [1-12] ID of the message 1
MessageTimeStamp M DateTime [19] Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00

Response GetDeliveryDate

Attribute Description Example
Deliverydate Response with the delivery date 30-06-2016
Options The delivery options for which a delivery date
is returned. Only one delivery option is specified. See Guidelines for possible values. Daytime

Request GetSentDate

GetSentDate type

Attribute Mandatory Format Description Example
AllowSundaySorting M Boolean [true/false] Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday). true
City O String [0-35] City of the address   Hoofddorp
Countrycode M String [2] The ISO2 country codes NL
DeliveryDate M Date [10] Date of the expected delivery (to the final destination) of the shipment. Format: dd-mm-yyyy 30-06-2016
HousNr O String [0-35] The house number of the delivery address 42
HouseNrExt O String [0-35] House number extension A
Options M String [7-9]
The delivery options for which a delivery date
should be returned.
Note that for now all the options are processed as Daytime option (see Guidelines).
Daytime
PostalCode M String [4-10] Zipcode of the address 2132WT
ShippingDuration M Integer [1] The duration it takes for the shipment to be delivered to PostNL in days. A value of 1 means that the parcel will be delivered to PostNL on the same day as the date specified in ShippingDate. A value of 2 means the parcel will arrive at PostNL a day later etc. 1
Street O String [0-95] The street name of the delivery address. Siriusdreef

Message type

Attribute Mandatory Format Description Example
MessageID M String [1-12] ID of the message. 1
MessageTimeStamp M Datetime [19] Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00

Response GetSentDate

Attribute Description Example
Sentdate Response with the sent date.
29-06-2016

Path	Description
/calculate/date/delivery	Calculates the expected delivery date for a shipment based on the retrieved parameters.
/calculate/date/shipping	Calculates the date to send the shipment based on the retrieved parameters.

Interface version	2_2
Sandbox endpoint	https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date
Sandbox wsdl	https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date/soap.wsdl
Sandbox swagger	https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date/swagger.json
Production endpoint	https://api.postnl.nl/shipment/v2_2/calculate/date
Production wsdl	https://api.postnl.nl/shipment/v2_2/calculate/date/soap.wsdl
Production swagger	https://api.postnl.nl/shipment/v2_2/calculate/date/swagger.json

API	Version	Release Date	Status	Release Notes	Schema Changes
DeliveryDate	1_0	Oct 7, 2013	Not supported
	1_1	Jan 24, 2014	Not supported	Different namespaces New additional method (GetSentDate)	Yes
	1_2	Aug 14, 2014	Not supported	Different namespaces	Yes
	2_0	Aug 14, 2015	Not supported	CutOffTime and CutOffTimeForSundaySorting replaced by CutOffTimes list In the previous version of the GetDeliveryDate method, cut off times were specified for weekdays and Sunday in two fields. It is now possible to specify cut off times for every day of the week in the new CutOffTimes field. To replicate the old functionality in the new message format, replace the CutOffTime field by a CutOffTime in the CutOffTimes list with Day value 00 and replace the CutOffTimeForSundaySorting field by a CutOffTime in the CutOffTimes list with Day value 07. Options field added It is now possible to specify which delivery options should be considered when returning a delivery or sent date using the new Options field. The GetDeliveryDate method will also specify which delivery option is applicable to the returned delivery date in the new Option field. See the interface specification for more details on the available delivery options. The new Options field is mandatory. To replicate the old 1_2 functionality, specify delivery option Daytime. New and updated address fields Several address fields have been added to the GetDeliveryDate and GetSendDate elements to specify the delivery address more precisely. These fields are: Street, HouseNrExt, City and CountryCode. CountryCode is a mandatory field. For an address in the Netherlands, specify NL for this field. In 1_2, the PostalCode field was only mandatory when AllowSundaySorting was set to true. It is always mandatory in 2_0. Furthermore, the HouseNumber field has been renamed to HouseNr.	Yes
	2_1	Nov 03, 2015	Supported	GetDeliveryDateResponse. Option is removed from the interface. GetDeliveryDateResponse. Options is added to the interface.	Yes
	2_2	Aug 24, 2017	Current Version	The following fields have been added to the interface: OriginCountryCode CutoffTime.Available New delivery option: MyTime (Delivery on demand) PRODUCT NO LONGER EXISTS	Yes

Options	Description
Daytime	Daytime delivery
Evening	Evening delivery
Morning	Morning delivery before 10:00
Noon	Morning delivery before 12:00
Today*	Delivery on day of handover to PostNL
Sunday	Sunday delivery
Sameday	Sameday delivery (must be used in combination with Evening)
Afternoon	Afternoon delivery before 17:00
* The Today delivery option will be returned on any given day (Mon – Sun), but will only be on the first following business day.

Attribute	Mandatory	Format	Description	Example
AllowSundaySorting	M	Boolean [true/false]	Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).	true
City	O	String [0-35]	City of the address	Hoofddorp
Countrycode	M	String [2]	The ISO2 country codes	NL
CutOffTimes	M	CutOffTime type	Cut off times per day. At least one cut off time must be specified.
HouseNr	O	String [0-35]	The house number of the delivery address	42
HouseNrExt	O	String [0-35]	House number extension	A
Options	M	String [7-9]	The delivery options for which a delivery date should be returned. Only one delivery option can be specified. See Guidelines for possible values.	Daytime
OriginCountryCode	O	String [2]	Origin country of the shipment Default NL Possible values NL and BE.	NL
PostalCode	M	String [4-10]	Zipcode of the address	2132WT
ShippingDate	M	Datetime [19]	Date/time of preparing the shipment for sending. Format: dd-mm-yyyy hh:mm:ss	29-06-2016 14:00:00
ShippingDuration	M	Integer [1]	The duration it takes for the shipment to be delivered to PostNL in days. A value of 1 means that the parcel will be delivered to PostNL on the same day as the date specified in ShippingDate. A value of 2 means the parcel will arrive at PostNL a day later etc.	1
Street	O	String [0-95]	The street name of the delivery address.	Siriusdreef