Timeframe

All the necessary information for implementing this API.

Customers convenience
Using this API in combination with the Deliverydate API give your customers more information and control about the arrival of the parcels.

Time windows based on experience and driving routes
The indication is based on past experience and is dynamic data. It is not guaranteed that for a given postal code the timeframe has the same timeframe a week later.

Ensure if delivery options are available at the requested address
If there is no timeframe available for the given date, postal code an delivery option, you get a reason why no timeframe information is available.

GetTimeframes
Using this API 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, Sameday and Today 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” or “Today” option in the request, depending on the chosen delivery option.

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

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

To ensure Evening or Today delivery is available at the requested address, it is mandatory to us the Timeframe webservice. If this option is not used, 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 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, Sunday and Today. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager. For Sunday, Sameday and Today delivery it is even mandatory to consult your account manager.

*Today is the product name for one of PostNL services and will be returned as Today on any given day when choosing this delivery option.

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.