Delivery options

The PostNL API allows you to retrieve a list of predicted timeframes and a list of possible pickup locations. For timeframes you will have to use a certain date range and to get the nearest pickup locations you can use an address or geolocation.

There are two ways to gather timeframes and pickup locations. You can

combine the delivery date, timeframe and location webservices
or use the checkout service.

The checkout service is currently not supported, but this library contains an easy interface to combine the three separate services listed in this section and provides the same functionality, if not more.

This section lists all the ways in which you can retrieve delivery options, using three webservices. It is possible to request:

Delivery dates (when a shipment could arrive, given the current shipping date)
Shipping dates (when a shipment should be dispatched, given the predicted delivery date)
Timeframes
Nearest locations
Nearest locations by coordinates

Checkout

On an e-commerce checkout page you will probably want to show timeframes and/or pickup locations based on the current day and cut-off window. This library provides an interface to easily combine the three webservices required to show all the delivery options. It will simultaneously contact the three webservices and request a list of timeframes and pickup locations based on the given input.

An example of how the interface can be used can be found in the section Requesting timeframes, locations and the delivery date at once, part of the Quickstart chapter.

Deliverydate webservice

Note

PostNL API documentation for this service:

https://developer.postnl.nl/apis/deliverydate-webservice

Use the delivery date webservice to determine the delivery and shipping date. You can use this service to calculate the dates ‘live’ and to make sure you do not promise your customers any timeframes that are no longer available.

Delivery dates

Here’s how you can retrieve the closest delivery date:

<?php

use Firstred\PostNL\Entity\CutOffTime;
use Firstred\PostNL\Entity\Request\GetDeliveryDate;

$cutoffTime = '15:00:00';
$dropoffDays = [1 => true, 2 => true, 3 => true, 4 => true, 5 => true, 6 => false, 7 => false];
foreach (range(1, 7) as $day) {
    if (isset($dropoffDays[$day])) {
        $cutOffTimes[] = new CutOffTime(
            str_pad($day, 2, '0', STR_PAD_LEFT),
            date('H:i:00', strtotime($cutoffTime)),
            true
        );
    }
}
$deliveryDate = $postnl->getDeliveryDate(
    (new GetDeliveryDate())
        ->setGetDeliveryDate(
            (new GetDeliveryDate())
                ->setAllowSundaySorting(false)
                ->setCountryCode('NL')
                ->setCutOffTimes($cutOffTimes)
                ->setHouseNr('66')
                ->setOptions(['Morning', 'Daytime'])
                ->setPostalCode('2132WT')
                ->setShippingDate(date('d-m-Y H:i:s'))
                ->setShippingDuration('1')
        )
);

The result will be a GetDeliveryDateResponse. Calling getDeliveryDate on this object will return the delivery date as a string in the d-m-Y H:i:s PHP date format.

The function accepts the following arguments

getDeliveryDate: Required: True

The Firstred\PostNL\Entity\Request\GetDeliveryDate request object. See the API documentation for the possibilities. As shown in the example you will need to provide as many details as possible to get accurate availability information.

Shipping dates

The Shipping Date service almost works in the same way as the Delivery Date service, except this time you provide the actual delivery date in order to calculate the closest shipping date.

<?php

use Firstred\PostNL\Entity\Request\GetSentDate;
use Firstred\PostNL\Entity\Request\GetSentDateRequest;

$deliveryDate = $postnl->getSentDate(
    (new GetSentDateRequest())
        ->setGetSentDate(
            (new GetSentDate())
                ->setAllowSundaySorting(false)
                ->setCountryCode('NL')
                ->setHouseNr('66')
                ->setOptions(['Morning', 'Daytime'])
                ->setPostalCode('2132WT')
                ->setShippingDate(date('d-m-Y H:i:s'))
                ->setShippingDuration('1')
        )
);

The function accepts the following arguments

getSentDate: Required: True

The Firstred\PostNL\Entity\Request\GetSentDateRequest request object. See the API documentation for the possibilities. As shown in the example you will need to provide as many details as possible to get accurate availability information.

Timeframe webservice

Note

PostNL API documentation for this service:

https://developer.postnl.nl/apis/timeframe-webservice

Timeframes

<?php

use Firstred\PostNL\Entity\CutOffTime;

$deliveryDaysWindow = 7;
$dropoffDelay = 0;

$timeframes = $postnl->getTimeframes(new GetTimeframes())
    ->setTimeframe([
        (new Timeframe())
            ->setCountryCode('NL')
            ->setEndDate(date('d-m-Y', strtotime(" +{$deliveryDaysWindow} days +{$dropoffDelay} days")))
            ->setHouseNr('66')
            ->setOptions(['Daytime', 'Evening'])
            ->setPostalCode('2132WT')
            ->setStartDate(date('d-m-Y', strtotime(" +1 day +{$dropoffDelay} days")))
            ->setSundaySorting(false)
    ])
);

timeframes: Required: True

The Firstred\PostNL\Entity\Request\GetTimeframes request object. See the API documentation for more details.

Location webservice

Note

PostNL API documentation for this service:

https://developer.postnl.nl/apis/location-webservice

The location service allows you to retrieve a list of locations for the given postcode or coordinates.

Nearest locations

Here’s an example of how you can retrieve the nearest location by postcode:

<?php

use Firstred\PostNL\Entity\Location;
use Firstred\PostNL\Entity\Request\GetNearestLocations;

$postnl->getNearestLocations(
    (new GetNearestLocations())
        ->setCountrycode('NL')
        ->setLocation(
            (new Location())
                ->setAllowSundaySorting(false)
                ->setDeliveryOptions(['PG'])
                ->setOptions(['Daytime'])
                ->setHouseNr('66')
                ->setPostalcode('2132WT')
        )
);

getNearestLocations: Required: True

The Firstred\PostNL\Entity\Request\GetNearestLocations request object. See the API documentation for more details.

Nearest locations by coordinates

You can also get the locations by specifying a bounding box. One can be drawn by providing the North-West and South-East corner of the box:

<?php

use Firstred\PostNL\Entity\CoordinatesNorthWest;
use Firstred\PostNL\Entity\CoordinatesSouthEast;
use Firstred\PostNL\Entity\Location;
use Firstred\PostNL\Entity\Request\GetLocationsInArea;

 $postnl->getLocationsInArea(
     (new GetLocationsInArea())
         ->setCountrycode('NL')
         ->setLocation(
             (new Location())
                 ->setAllowSundaySorting(false)
                 ->setDeliveryDate(date('d-m-Y', strtotime('+1 day')))
                 ->setDeliveryOptions([
                     'PG',
                 ])
                 ->setOptions([
                     'Daytime',
                 ])
                 ->setCoordinatesNorthWest(
                     (new CoordinatesNorthWest())
                         ->setLatitude((string) 52.156439)
                         ->setLongitude((string) 5.015643)
                 )
                 ->setCoordinatesSouthEast(
                     (new CoordinatesSouthEast())
                         ->setLatitude((string) 52.017473)
                         ->setLongitude((string) 5.065254)
                 )
         )
 );

This function accepts the arguments:

locationsInArea: Required: True

The Firstred\PostNL\Entity\Request\GetLocationsInArea request object. See the API documentation for more details.