Documentation

• Name: Timeframe Webservice
• Reason to Call: To get a timeframe in which a parcel is estimated to be delivered.
• Input: Details of dates, delivery options and the address of the customer.
• Output: Timeframes and the possible reason no timeframe could be given.

The following methods are defined within the Timeframe WebService: 

* 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.

REST:

SOAP:

GetTimeframes
Using this web service allows you to predict a time frame for a maximum of 17 days.* During this period, you will receive time frames for all the delivery options you specify. This method is ideal if you want to show a calendar and/or frame where your customers can decide on the date and time of delivery for their order. It is also possible to offer your customer a couple of delivery time frames. For example, you can show the Evening and/or Morning delivery possibilities for the coming week.

* Posting a time frame for longer than two weeks is not recommended. This is because a time frame is dynamic data and so it cannot be guaranteed that it will be the same for a given postal code two weeks later.

Be aware that you need to hold on to a customer’s parcel until the date they have requested. Entrusting it to PostNL too early will result in it being delivered too soon. You can use the ‘Deliverydate webservice’ to determine the exact ‘sentdate’ for handing the parcel over to PostNL to ensure your customer receives it exactly on time - neither too early nor too late.

Evening and Sameday delivery
It is possible that PostNL Pakketten delivers at every evening on a weekday. However, we do not deliver to every address. To know if we deliver to a given postal code, you will have to specify the “Evening” option in the call.

We also have the option to ship parcels on the same day. To know if Sameday delivery is available, you must select both the “Sameday” and the “Evening” option in the GetTimeframes call.

If you want to offer Evening and Sameday delivery, realize that you will also have to adjust your shipping requests (labels and confirming).

To not disappoint your customer, we advise you to request Evening timeframes first, and only show the possibility when Evening timeframes are returned by the webservice call. Otherwise, the suggestion is made that the parcel can be delivered in the evening, and in some areas there is no evening delivery possible.

Sunday delivery
PostNL Pakketten offer the possibility to deliver parcels on a Sunday. You can use the delivery option “Sunday” in the request to receive the timeframe for Sunday. Not all the products can be used for Sunday delivery. For a list of available products, see the Products page at How to Use of the labelling and confirming webservices.

Response
The response is divided into two parts, ReasonNoTimeframe and Timeframe. TimeFrame is the most interesting because all the available periods between the given start and end dates are shown in this response.

Every timeframe in the response has at least one period under TimeFrames. Exact information of each period is shown at TimeFrameTimeFrame, whereby all values are strings. This allows to distinguish between the delivery periods. The following values can be specified in the options element:

All the above delivery options can be used in the request of the timeframe webservice. PostNL will charge an additional amount for delivery of the parcels with the options Evening, Morning, (After)Noon, Sameday and Sunday. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager.

ReasonNoTimeframe codes
There are several reasons why there isn’t timeframe information available. Below you can find the codes and the specific reasons.

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

Timeframe_Error_Codes