Shipping items to pickup points (BETA)

This functionality can only be used if you configured a pickup point calendar through SDD and are participating in the pilot.

1. Introduction

Shipping items to pickup points allow you to not only deliver customer packages at someone’s home or office address, but also to send them to a drop-off point so that customers can pick up a package at their own convenience. This page describes how this functionality can be used when using the Retailer API version 3 and 4 (the links provided in this document point to v4).

Before continuing, please take note of the following:

  • Read the below instruction carefully. If you do not comply with the instructions below, your parcels will be rejected at the pickup point location. This will count negatively on your PPM score.

  • At this moment, it is only possible to ship orders towards pickup points in the Netherlands of Albert Heijn (AH)

  • It is only possible to ship items with PostNL to AH pickup point locations. Therefore, only shipments with PostNL will be accepted by the API. In case you still send items with a different transporter, they will be rejected at the pickup point location.

  • Shipping packages to pickup points is only possible through API version 3 and higher. In case you are using an older version, make sure you upgrade your connection first if you are interested in this functionality.

2. Logical process flow

In order to enable this functionality, the following steps are required:

  • Make sure you are participating in the pilot

  • Configure your calendar in SDD to let us know when you are working. Refer to the partner platform for more information.

  • Create an offer with a pickup point calendar

  • Receive your order with a pickup point indication

  • Ship your item to the pickup point address specified in the order

  • This process flow will impact the following endpoints within the API:

Orders and Shipments

3. Creating, updating, and receiving an offer with a pickup point identifier

Sending items towards pickup points is an additional delivery method that you can apply on top of a regular delivery type. With that in mind, be aware that a pickup point delivery is not a replacement for home delivery. Therefore, you always need to provide a deliveryCode and optionally a pickup point calendar.

At this moment, you can only ship items to Albert Heijn in the Netherlands, identified by the fixed pickup point code PUP_AH_NL.

Create an offer with a pickup point calendar

This pickup point code (PUP_AH_NL) is an additional field that has been added to the fulfilment element on the offer. See ReDoc offer documentation for a code example. This field indicates if you want this offer to be shipped to a pickup point location.

Update an offer with a pickup point calendar

When updating an offer with a pickup point calendar, the exact same logic applies when creating an offer. See ReDoc put offer for a code example. In case you want to remove the pickup point calendar from this offer, you can omit the pickup point location entirely from the payload.

Receiving an offer with a pickup point calendar

When fetching an offer from the API, the deliveryLocation can found under the fulfilment element in the response. See ReDoc get offer for a code example.

4. Receiving pickup point orders

When fetching a single order, two new fields have been introduced to indicate that this order is an order that requires shipment to a pickup point:

  1. pickUpPoint - indicates whether this order must be shipped to a pickup point or not

  2. pickUpPointName - indicates the location name of the pickup point (for example ALBERT HEIJN UTRECHT)

The pickupPointName field indicates the location of the pickup point. In case the pickupPointName is filled, the shipmentDetails are updated with the address and location of the pickup point location. Be advised that therefore this data is not customer data, but shipment data. Customer data for billing information can be found under the billingDetails object.

Be aware that the pickupPointName is also present under billingDetails, but that will always be empty.

5. Shipping label requirements

When creating a shipping label (either yourself or via a 3rd party plugin), please be advised that the name of the customer is required on the shipping label for identification purposes. Please make sure to add the entire name to the shipping label (firstName and surname fields) to avoid rejection at the pickup point location. In case you are purchasing a label from bol.com, the customer’s name is automatically printed on the label for you.

6. Receiving pickup point shipments

When fetching shipment data, the same new fields have been introduced as in the order. You can find the relevant data there for future reference.