Explore the updated APIs
Shipment API v4
New: Returns API v4
A separate API for returns: clearer, more reliable and tailored to your returns process.
Checkout APIs v4
What is Shipment API v4?
The Shipment API v4 makes it easier to create and pre-notify shipments. Instead of using complex product codes, you now use clear product names. This reduces errors and speeds up your process.
What are the benefits?
Clear product names
Fewer mistakes when pre-notifying and easier to use.
More label flexibility
Choose portrait or landscape labels and the file type that fits your printer.
Aligned with our processes
Terminology now matches contracts and invoicing.
When and how to switch?
Shipment API v4 and Returns API v4 will be available from May 2025. You can already start the transition. The current Labelling and Shipping APIs will no longer be supported after end of 2026.
Check the step-by-step guide and technical docs on the developers portal.
What is Returns API v4?
The return functionality has been removed from the old Shipping API and is now handled by a new, separate API. That’s because returns follow a different flow than shipments – and this API reflects that difference.
What are the benefits?
Designed for returns
Submit returns separately, without unnecessary shipping options.
Fewer errors
You only submit what’s needed – nothing more.
More clarity
Shipping and returns are clearly separated.
When and how to switch?
Returns API v4 will be available from May 2025. You can already start the transition. After end of 2026, returns via the old Shipping API will no longer be supported.
Check the step-by-step guide and technical docs on the developers portal.
What are the Checkout APIs v4?
The new Checkout APIs v4 align fully with Shipment API v4. Thanks to consistent structure and terminology, it's easier to configure shipping and delivery options.
What are the benefits?
Fast integration
From delivery time to extra services: it all works the same.
Consistent options
The APIs work together seamlessly, requiring less configuration.
Clearer for your customers
Make it easy to offer clear choices in your checkout.
When and how to switch?
Checkout APIs v4 are expected in Q3 2025. The current APIs will be phased out by end of 2026. We’ll notify you when it’s time to switch.
Applies to all updated APIs
- APIs are REST-based and replace the older SOAP versions
- SFTP is replaced by real-time data exchange
- Multi-Factor Authentication adds extra security
- Life cycle management means more predictable updates and less maintenance
See all developments on the overview page.
Other questions
Yes and no. If you’ve switched to all three, you’re fully up to date for your checkout and warehouse integration.
But we continue to improve our APIs. With API life cycle management, future updates will be rolled out in a controlled way. So it's important to keep your integration up to date.
If you use the current Labelling and/or Shipping API, switch to Shipment API v4. If you also handle returns, you’ll need to use the new Returns API v4 – returns are no longer supported in the Shipment API.
The Confirming API remains unchanged for now. We’ll share updates later.
You’ll receive a message when it’s your turn to switch. From that moment, you’ll have about one year. After that, the old APIs will no longer be supported.
Key milestones:- Q2 2025: Shipment API v4 and Returns API v4 available
- Q3 2025: Checkout APIs v4 available
- End of 2026: Old APIs phased out and no longer supported
If you don’t switch in time, you won’t be able to pre-notify shipments via the old APIs anymore.
- Migration step-by-step guide
- Integration guidelines
- Open API Specification (OAS)
- Overview of available products and services
- Frequently asked questions (FAQ)
Documentation for Checkout APIs v4 will follow soon.
If you still have questions after reading the documentation, contact our Channel Integrations team via the support form on the developer portal.
If you have a PostNL account manager, they are your first point of contact and can escalate questions internally if needed.
Yes. You can test your implementation in the Sandbox environment. To access it, request a new API key via the support form on the developer portal. You’ll then be directed to Mijn PostNL Zakelijk to select the right key from the dropdown.
The new key covers both updated and existing APIs. After successful testing, request approval to access the production environment.
Yes, you’ll need a new API key for the new APIs. You’ll find instructions on how to request one on the developer portal.
Your existing keys will remain active until you fully switch over. New keys work across both updated and current APIs. The request follows the usual process – we can’t send API keys in an unsecured way.
These APIs are available to Dutch customers who want to create e-commerce shipments (including barcodes, labels and pre-notification) for deliveries in the Netherlands, Belgium or internationally.
In the course of 2025, we’ll expand available services. Support for Belgian customers (shipments from Belgium) will follow later in 2025.
For the most up-to-date product and service overview, visit the developer portal.
Shipment API v4 covers nearly all current parcel products for Dutch customers, including (letterbox) parcels to the Netherlands, Belgium and abroad. We’ll add more services over time. Support for Belgian senders will follow later in 2025.
Note: Special services such as Extra@Home, Pharma and Care are not yet available in the new APIs. You can continue to use your current API for those for now.
We’re continuously updating the product offering. For the latest information, visit the developer portal.