Why use the Shipping status API
Real-time status information
The current status and the complete status can be requested. With the Detail boolean in the request (true) gives you an overview of all the statuses that are given to the parcel throughout the distribution process.
Retrieve all your updated statuses
With the method ‘updatedshipments' you can retrieve (all) the updated statuses for a particular customer number.
Restricted to your personal codes
To match the customer data to the parcels by the combination of customer number and code. Only if the customer data and the parcels match, the information is disclosed.
Get started
Documentation
View our exhaustive documentation.
Postman
All of our API's available as Postman collections.
Github
Find PostNL on Github.
Sandbox
Test your integration by copying the endpoint.
Guidelines
Learn more about the Shipping status API guidelines.
Use of the webservice
Please be aware that this service is meant for single requests* about a parcel and not designed to update the status every single minute on all your parcels. This is important because the capacity of our network is limited. So, please ensure that this service is only called in useful intervals, and for relevant shipments only. PostNL suggests the following usage:
- Only call ShippingStatus for an update when needed by a customer application or user.
- Limit the number of days that will be searched for better performance with the parameter 'maxDays'.
- Only set the parameter 'Detail'on true (boolean), when exceptions have occurred and more detailed statuses are needed.
- Only call ShippingStatus after a shipment can have a status update (for example: request status in afternoon after delivery to PostNL, then it will have been sorted and delivered, giving useful information).
- Stop calling ShippingStatus when the barcode is not found or an error has occurred.
Security policy
The statuses about your parcels are restricted to your company (customercode and customernumber). Our security policy is designed to identify which company is requesting the information and matches that information with the parcels sent by the company. Only if the company and the parcels match, the information is disclosed.
GetSignature response
This method returns a GIF image (base64 encoded). To retrieve a working image you need to convert and decode this string and mark the mime-type of the image as GIF.
Using the response information
You can use the response information of the webservice to inform your own customers proactively about the status of their parcels. As the status we return is a near to real-time status, it is recommended to communicate this status as soon as possible to your customers.
Warnings
When the parcel requested is not found, the service returns a warning message.
Error codes
Error codes have been specified in the Error codes section. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.