Documentation

Deliverydate webservice

Summary

  • Name: Deliverydate Webservice.
  • Reason to Call: Find out the expected delivery date or proposed sent date of the parcels.
  • Input: Address, postalcode, shipping- or delivery date and delivery options.
  • Output: Delivery date and Sent date.

Methods

The following methods are defined within the Deliverydate WebService: 

Methods

Description

GetDeliveryDate

Calculates the expected delivery date for a shipment based on the retrieved parameters.

GetSentDate

Calculates the date to send the shipment based on the retrieved parameters.

Methods

SoapAction

GetDeliveryDate

http://postnl.nl/cif/services/DeliveryDateWebService/IDeliveryDateWebService/GetDeliveryDate

GetSentDate

http://postnl.nl/cif/services/DeliveryDateWebService/IDeliveryDateWebService/GetSentDate

Call details

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

* PostNL has launched a new API platform since 24 August 2017. The former webservices have been migrated to this platform, so that we can keep providing good service. It is recommended to use the above endpoints.

If you already use the former API’s (endpoint: https://service.postnl.com/CIF/) and you want to make use of the new endpoints, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.

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)

 N/A


SOAP:


API 

Version

Release Date

Status

Release Notes

Schema Changes

DeliveryDate

1_0

Oct 7, 2013

Supported

 

 

1_1

Jan 24, 2014

Supported

Different namespaces
New additional method (GetSentDate)

Yes

1_2

Aug 14, 2014

Supported

Different namespaces

Yes

2_0

Aug 14, 2015

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

Current Version

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)

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

Sunday

Sunday delivery

Sameday

Sameday delivery (must be used in combination with Evening)

Afternoon

Afternoon delivery before 17:00  

MyTimeMytime delivery (In Dutch: Op Afspraak bezorgd)

Delivery options (GetSentDate)
It is also possible to specify the above delivery options when returning a sentdate by using the Options field.
Note: For now 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

Request GetDeliveryDate

GetDeliveryDate type

AttributeMandatoryFormatDescriptionExample
AllowSundaySortingMBoolean [true/false]Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).true
CityOString [0-35] City of the address  Hoofddorp
CountrycodeMString [2] The ISO2 country codes NL 
CutOffTimesMCutOffTime typeCut off times per day. At least one cut off time must be specified. 
HousNrOString [0-35] The house number of the delivery address42
HouseNrExtOString [0-35] House number extension A
OptionsMString [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

OString [2] Origin country of the shipment
Default NL
Possible values NL and BE.
NL
PostalCodeMString [4-10] Zipcode of the address2132WT
ShippingDateMDatetime [19] Date/time of preparing the shipment for sending. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 14:00:00
ShippingDurationMInteger [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
StreetOString [0-95] The street name of the delivery address.Siriusdreef

CutOffTime type

AttributeMandatoryFormatDescriptionExample
Day MInteger [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
TimeMTime [8] The cut off time for this day of week.
Format: hh:mm:ss
14:00:00
AvailableOBoolean [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

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12]ID of the message1
MessageTimeStampMDateTime [19]Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss29-06-2016 12:00:00

Example

POST https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/DeliveryDateWebService/IDeliveryDateWebService/GetDeliveryDate"
apikey: **********
Content-Length: 2191
Connection: Keep-Alive


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:del="http://postnl.nl/cif/services/DeliveryDateWebService/" xmlns:tpp="http://postnl.nl/cif/domain/DeliveryDateWebService/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Body>
    <del:GetDeliveryDate xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://tntpost.nl/parcels/CIF/DeliveryDateWebService/">
      <tpp:GetDeliveryDate>
        <tpp:AllowSundaySorting>true</tpp:AllowSundaySorting>
        <tpp:City>Hoofddorp</tpp:City>
        <tpp:CountryCode>NL</tpp:CountryCode>
        <tpp:CutOffTimes>
          <tpp:CutOffTime>
            <tpp:Day>00</tpp:Day>
            <tpp:Time>14:00:00</tpp:Time>
          </tpp:CutOffTime>
        </tpp:CutOffTimes>
        <tpp:HouseNr>42</tpp:HouseNr>
        <tpp:HouseNrExt>A</tpp:HouseNrExt>
        <tpp:Options>
          <arr:string>Daytime</arr:string>
        </tpp:Options>
        <tpp:PostalCode>2132WT</tpp:PostalCode>
        <tpp:ShippingDate>29-06-2016 14:00:00</tpp:ShippingDate>
        <tpp:ShippingDuration>1</tpp:ShippingDuration>
        <tpp:Street>Siriusdreef</tpp:Street>
      </tpp:GetDeliveryDate>
      <tpp:Message>
        <tpp:MessageID>1</tpp:MessageID>
        <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
      </tpp:Message>
    </del:GetDeliveryDate>
  </soapenv:Body>
</soapenv:Envelope>

Response GetDeliveryDate

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

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetDeliveryDateResponse>
xmlns="http://postnl.nl/cif/services/DeliveryDateWebService/"
xmlns:a="http://postnl.nl/cif/domain/DeliveryDateWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
         <a:DeliveryDate>30-06-2016</a:DeliveryDate>
         <a:Options xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <b:string>Daytime</b:string>
         </a:Options>
      </GetDeliveryDateResponse>
   </s:Body>
</s:Envelope>

Request GetSentDate

GetSentDate type

AttributeMandatoryFormatDescriptionExample
AllowSundaySortingMBoolean [true/false]Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).true
CityOString [0-35] City of the address  Hoofddorp
CountrycodeMString [2] The ISO2 country codes NL 
DeliveryDateMDate [10] Date of the expected delivery (to the final destination) of the shipment. Format: dd-mm-yyyy30-06-2016
HousNrOString [0-35] The house number of the delivery address42
HouseNrExtOString [0-35] House number extension A
OptionsMString [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
PostalCodeMString [4-10] Zipcode of the address2132WT
ShippingDurationMInteger [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
StreetOString [0-95] The street name of the delivery address.Siriusdreef

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message.1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00

Example

POST https://api-sandbox.postnl.nl/shipment/v2_2/calculate/date HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/DeliveryDateWebService/IDeliveryDateWebService/GetSentDate"
apikey: **********
Content-Length: 1817
Connection: Keep-Alive


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:del="http://postnl.nl/cif/services/DeliveryDateWebService/" xmlns:tpp="http://postnl.nl/cif/domain/DeliveryDateWebService/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Body>
    <del:GetSentDateRequest>
      <tpp:GetSentDate>
        <tpp:AllowSundaySorting>true</tpp:AllowSundaySorting>
        <tpp:City>Hoofddorp</tpp:City>
        <tpp:CountryCode>NL</tpp:CountryCode>
        <tpp:DeliveryDate>30-06-2016</tpp:DeliveryDate>
        <tpp:HouseNr>42</tpp:HouseNr>
        <tpp:HouseNrExt>A</tpp:HouseNrExt>
        <tpp:Options>
          <arr:string>Daytime</arr:string>
        </tpp:Options>
        <tpp:PostalCode>2132WT</tpp:PostalCode>
        <tpp:ShippingDuration>1</tpp:ShippingDuration>
        <tpp:Street>Siriusdreef</tpp:Street>
      </tpp:GetSentDate>
      <tpp:Message>
        <tpp:MessageID>1</tpp:MessageID>
        <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
      </tpp:Message>
    </del:GetSentDateRequest>
  </soapenv:Body>
</soapenv:Envelope>

Response GetSentDate

Attribute  DescriptionExample
Sentdate   Response with the sent date. 

29-06-2016 

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetSentDateResponse
xmlns="http://postnl.nl/cif/services/DeliveryDateWebService/"
xmlns:a="http://postnl.nl/cif/domain/DeliveryDateWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
         <a:SentDate>29-06-2016</a:SentDate>
         <a:Options xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
       </GetSentDateResponse>
   </s:Body>
</s:Envelope>