Use case

1) How to validate Dutch address data in the checkout?


2) How do I implement PostNL in the webshop checkout?


3) How do I process the orders (and the customers' delivery choice)?


Check address data which is entered in your checkout.
View details


Step 1

Fast and reliable delivery by PostNL
View details


Step 2

Process customer name and address details + product info
View details

4) How do I prepare shipments

5) How do I communicate the order status to my customers and customer service employees?!                                  


6) How does the return process work for me and my customers?

Step 3                     pijl

Print labels and send a confirmation to PostNL
View details                      

                                        Step 4

Track and trace the parcels
     View details




              Step 5

               Create return labels
               View details

1. How to validate Dutch address data in the checkout?

PostNL offers the ability to control the checkout process of the webshop consumers and improve the quality of CRM data. With the Checkout Postalcode Check API you can ensure that your customers always fill in the correct address data. All they have to do is enter a postalcode and housenumber(+ housenumber addition) and it corresponding address appears automatically. If this information is incorrect, then let a pop-up or message show up to tell something went wrong with the address data.

2. How do I implement PostNL in the webshop checkout?

If you offer a variety of solutions for the delivery of online orders, this will guarantee an increase in sales. With the PostNL delivery options you offer your customers convenience and the ability to decide when and where to receive their parcels. Flexibly, quickly and at their desired time. So depending on what you want to send, it is recommended to implement these options in your checkout. For most Dutch domestic products we offer several delivery options. However, for some products, it is not possible to show PostNL information about receiving them. But despite this restriction, it is still advisable to mention something about the delivery in your checkout. 

First of all, choose what kind of product you want to send. If you send products without delivery option possibilities, go straight to Step 2.

Products with delivery option possibilities:                    

Products without delivery option possibilities:            
If you send a combination of the above products and one of these products are Dutch or Belgium destination products; you can only implement the available PostNL delivery options in your checkout for these products.

2.1 How do I implement delivery options in the webshop checkout?

Enhance your customer's online shopping experience by providing more control over the delivery of their purchased product.
Integrate the PostNL frontend webservices into your checkout and empower your customers to choose the delivery option that suits them best.


①  First use the GetDeliveryDate method to determine the available delivery dates (based on the shipping date, duration and your availability). Use the received (delivery)date of the response as a starting point for the Timeframe API. This is the Startdate in the Timeframe request (See 2).

②  By the use of the Timeframe API the delivery window can be created. With the obtain timeframes the possible days and related (estimate) time of arrival of the products can be shown.
Use the customers address in the request to determine the possible timeframes for the given period. Avoid showing delivery dates and options (see 3) that are not available.

By adding 'Options' (e.g. Evening, Sameday or Sunday) to the timeframe request, the delivery window can extend with delivery options. The Timeframe API also check whether delivery ‘Options’ are available at the given customers address.

The Location API can be used to show the (nearest) pick up points based on the customer address or latitude/longitude coordinates combination.

⑤ Customers can select a different location by clicking on the ‘kies een ander ophaalpunt’ (choose another pickup location). 

A list of available locations and opening hours can be shown. To show pick up points in a map, you will need to apply an API key at the Google Maps platform. When customers enters a different postalcode, the list (and the map) wil be updated automatically. For more information please refer to the Location API


 This Visual assets can be useful when creating a delivery option frame in your checkout.

2.2 Technical documentation

2.3 Excluded products

For the products below, it is not possible to let your customers choose the day and time of arrival or to send these products to a PostNL pickup location.

  • Mailbox sized parcels
  • International (Parcels EU and GlobalPack)
  • Extra@Home
  • Cargo

You can find information about these products on the Products page. Use this information in the order data processs (step 2).

3. How do I process the orders (and the customers' delivery choice)?

First of all, determine the shipment’s delivery date and/or delivery options. To process the orders you also need the consumer’s Name, Address and City data and make sure that you use the right product code for the delivery.
Each shipping product has its own product code and business rules which must be used for various API requests.
Please consult the Products page for more information on product codes , business rules and validations.

For example:

If you want to process an Evening delivery you must combine the product code with the following product options; characteristic 118, option 006.
In addition to the standard business rules the following information is required:

  • Delivery date is required.

    (Check that Evening Delivery is possible on your chosen date)

  • Receiver Address fields required:

    • Company name or last name
    • Street
    • House number
    • Postcode
    • City
  • Evening delivery must be allowed on the address specified
  • The receiver’s contact mobile phone number or email address is required.

4. How do I prepare shipments?

  • Create barcodes
    The barcode is an unique combination of letters and numbers that is used to identify your shipment.  and It is based on your customer code and number.
    Use this barcode in the request of the labelling webservice request.
    Barcode webservice
  • Create labels
    When using the ‘GenerateLabel WITH confirming’ method, the Confirming service no longer needs to be in your system because it is already integrated in this method. So you can skip the next step (Confirming). 
    Labelling webservice
  • Send a confirmation of the shipments.
    This is the final step in the flow. The confirmation contains information about the sender and receiver, the destination (city and country) and any additional delivery services applicable.
    Usually the confirming is sent along with creating a label (see above information). In some cases it is recommended to use both the Labelling WITHOUT confirming method and the Confriming API. For example if you need more time to process the parcels after picking and packing and you don't want consumers to be able to trace the parcels already.
    Confirming webservice

5. How do I communicate the order status to my consumers and customer service employees?

  • Get or retrieve status information about your parcels automatically.

    Use the barcodes (step 3) or your own parcel references to track them. Integrate this shipping status webservice in your backoffice system(s) for customer service employees or customer account environment and get (current) status information for your parcels.
    With the obtained track and trace information you can send personalized notification e-mails.
    ShippingStatus webservice

  • Online Track & Trace service.

    With this online service, you and/or your customers can check shipment delivery status quickly and easily.

     You can use this service to send transactional e-mails with track en trace information to your customers. This is also possible for internal use, as it is for customer service. Your employees will then be directed to Mijn PostNL, where they can access detailed Track & Trace information.
    Direct links Track & Trace

6. How does the return process work for webshops and consumers?

  • Return-to-sender label in the box
    PostNL offers return-to-sender labels along with their parcels. The labelling webservice can create these labels (see step 3) at the same time as the label for the original shipment.
    Your customers can use these labels to return the shipments free of charge via a PostNL location.
    Example label in the box request

  • Single label
    It is also possible to create single labels by using the labelling webservice. These labels can be sent to customers or made available to download from their customer account when they let you know they wish to return a shipment. *These labels are not linked to the original shipments*

    Your customers can return shipments via a PostNL location free of charge.
    Example single label request

Note: The return labels must always be addressed to a Business reply number (Antwoordnummer) and can only be used for Dutch Domestic products.


  • Smart Returns
    Your can offer your consumers the possibility of printing the return label at a PostNL location. An additional barcode will be added in the Labelling response. You can share this with consumers by email, so they can show this barcode on their smartphone. The barcode will be scanned and the return label will be printed.
    Details Smart Returns product

  • Return on Demand
    PostNL offers the possibility of picking up return parcels at specific locations / home addresses. By requesting the Return on Demand API, PostNL will provide available timeframes for the given location. After a time frame is chosen by the consumer, you can claim the specific timeframe.The consumer will be notified by PostNL that a parcel will be picked up at the requested time and address. The barcode of the return label (added by consumers) will be scanned at pickup.
    Return on Demand API