Documentation REST

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 DeleveryDataWebService:

Methods

JSON Action (GET)

Delivery

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

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 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 Swagger

https://api.postnl.nl/shipment/v2_2/calculate/date/swagger.json

If you already use the former SOAP API’s and/or you want to make use of the REST API’s, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.

Versioning

API

Version

Release Date

Status

Changes compared to the previous (SOAP) versions

Schema Changes

DeliveryDate

2_2

Jun 01, 2017

Supported

Different namespaces  (1_1)
New additional method (GetSentDate) (1_1)
Different namespaces (1_2)

CutOffTime and CutOffTimeForSundaySorting replaced by CutOffTimes list (2_0)
Options field added (2_0)

New and updated address fields (2_0)

GetDeliveryDateResponse.Option is removed from the interface. (2_1)

GetDeliveryDateResponse.Options is added to the interface. (2_1)

The following fields have been added to the interface:

OriginCountryCode

CutoffTime.Available

New delivery option: MyTime (2_2)

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 in the Delivery Date service.

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.

The Shipping duration is very important by using this webservice.  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.

Delivery options
It is 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 Option field. Only one delivery option can be specified.

Option

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  

Error codes
Error codes have been specified in the API Generic document. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in PostNL API.

Deliverydate_Error_Codes

Request and Response codes

For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.

Request and Response codes

For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.

Swagger UI

Test the RESTful API's with JSON content type format with the below Swagger tooling. To easily test the API: Click at 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.

You can also test this API's by using the following Swagger url: http://petstore.swagger.io/ (expand the url with /swagger.json and click Explore)