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.

Method

The following methods are defined within the Labelling WebService.

Methods

Description

Quote

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

Purchase

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 endpointhttps://api-sandbox.postnl.nl/shipment/v1/pickuporder
Sandbox swaggerhttps://api-sandbox.postnl.nl/shipment/v1/pickuporder/swagger.json
Production endpointhttps://api.postnl.nl/shipment/v1/pickuporder
Production swaggerhttps://api.postnl.nl/shipment/v1/pickuporder/swagger.json

Versioning

REST:

API

Version

Release Date

Status


Schema Changes

Return on Demand

1

Okt 01, 2018

Current version


 N/A

Guideline

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”).

Request

Example request (Quote) 

{
    "Customer": {
        "CustomerNumber": "11223344"
    },
    "Shipment": {
        "ServiceTypeID": "Collection",
        "Quantity": "1",
        "Dimension": {
            "Weight": "2000"
        },
        "Contacts": [{
                "ContactType": "01",
                "Email": "receiver@email.com",
                "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"
  }
}