Return on demand

PostNL offers the possibility of picking up return parcels at a specific location. This offers additional convenience for the consumer. By requesting the Return on Demand API call (quote), PostNL will provide available time frames for the given location. After a time frame is chosen by the consumer, you can request the Return on Demand API call (purchase) to claim the specific time frame.
• You share the available time frames with the consumer, e.g. as part of your webshop checkout where a return parcel is announced. The consumer chooses from the available timeframes.
• The consumer has to put a return label on the return parcel with a valid barcode.
• The consumer will be notified by PostNL that a parcel will be picked up at the requested address.
• The barcode will be scanned at pickup.


The following methods are defined within the Labelling WebService.




First, you have to check which timeframes are available for the specified address, the Quote.


To claim a timeframe, you post a purchase with one of the provided timeframes in the Quote response.

Call details

Interface version  (REST only)v1 
Sandbox endpoint
Sandbox swagger
Production endpoint
Production swagger





Release Date


Schema Changes

Return on Demand


Okt 01, 2018

Current version



The parcel that needs to be picked up, will have to contain a label with a valid 3S barcode, that has been confirmed separately to PostNL. The pickuporder service cannot be used with Smart Returns (“Printerloos Retourneren”).


Example request (Quote) 

    "Customer": {
        "CustomerNumber": "11223344"
    "Shipment": {
        "ServiceTypeID": "Collection",
        "Quantity": "1",
        "Dimension": {
            "Weight": "2000"
        "Contacts": [{
                "ContactType": "01",
                "Email": "",
                "SMSNr": "0612345678"
        "Addresses": [{
                "AddressType": "01",
                "Countrycode": "NL",
                "Zipcode": "1015EA",
                "City": "Amsterdam",
                "Street": "Prinsengracht",
                "HouseNr": "112",
                "HouseNrExt": "a",
                "Name": "ReceiverName"
            }, {
                "AddressType": "02",
                "Countrycode": "NL",
                "Zipcode": "1015NA",
                "City": "Amsterdam",
                "Street": "Noordermarkt",
                "HouseNr": "48",
                "HouseNrExt": "-56",
                "Name": "SenderName"

Example request (Purchase)

  "Customer": {
    "CustomerNumber": "11223344"
  "Shipment": {
    "ShipmentID": "62acef41-e37d-49e6-a5c1-162b796468c4",
    "CollectionTimeStampID": "ec0df6b7-2502-4132-b415-edf37e481777",
    "CollectionTimeStampStart": "2018-08-17T11:00:00.000+02:00",
    "CollectionTimeStampEnd": "2018-08-17T12:00:00.000+02:00"

Swagger UI

Test the RESTful API's with JSON content type format with the Swagger tooling. To easily test the API: Click at 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.

You can also test this API's by using the following Swagger url: (expand the url with /swagger.json and click Explore)

Return on demand

Picking up return parcels at a specific location