Postnl.nl

Timeframe

Documentation

This API provides you the opportunity to display the possible day and time of arrival of the parcels in the checkout of a webshop. Based on specified delivery options, you get timeframes which are an indication in a number of hours when a parcel can be received by your customers.

Development

All the necessary information for implementing this API.

Why use the Timeframe 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.

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

 

Guidelines

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.

Sustainable delivery option
You can show customers when their parcel can be delivered sustainably. In the response of the Timeframe API the follow sustainability codes be distinguished: 
 
Code 01 = Sustainable delivery 
Code 00 - Not available
 
You can build in the corresponding communication message in your checkout;
Sustainably delivered;  “Duurzaam bezorgd”
 
Not available: Not a sustainable option (yet).
 
Sustainably delivery
PostNL delivers the parcel to your address with an electric vehicle or with a sustainable fuel vehicle.
 
In the below file you can find the visual assets which you can you use in your checkout to show the sustainability options.

Visual assets
 
Please note that you can use the all-in-one Checkout API as well. This API combines the functionality of all the delivery and sustainability options.

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:

Option

Description

Daytime

Daytime delivery

Evening

Evening delivery

Morning

Morning delivery before 10:00

Noon

Morning delivery before 12:00

Sunday

Sunday delivery

Today*

Delivery on day of handover to PostNL

Sameday

Sameday delivery (must be used in combination with Evening)

Afternoon

Afternoon delivery before 17:00

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.

CodeDescription
Code 01Geen routeplan tijdvak (no timeframe available for this address in combination with this particular delivery option)
Code 02Geen commercieel tijdvak (not a commercial timeframe, reliability is too low)
Code 03Dag uitgesloten van tijdvak (no timeframe available at this day for this particular delivery option)
Code 04Uitgesloten adres (excluded address for timeframe indication)
Code 05Geen avondbelevering mogelijk (no evening delivery possible at this address/date)

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.