Changelog
Updates Developer Center
[14-10-2024] Change ZPL output of Zebra printers for international labels
On October 30, we will implement a change in the ZPL output of Zebra printers for international labels. The ZPL output will include the command ^LH0,0. This command ensures the correct alignment of the label. Additionally, we will remove the command ^MD30 from the ZPL output. This command was responsible for darkening the label output but did not always have the desired effect.
[2-9-2024] New T&T status codes (G03 + V06) added to most common SFTP connection
Per 4th September 2024, two extra scan observations are added to the most common SFTP connection. These scan observations provide more insight into when a shipment is delayed during peak periods. This gives you the opportunity to proactively inform recipients or answer their questions. Below an explanation of the extra scans.
T&T status code / Observation: G03
Description: NL: “Door drukte duurt de bezorging wat langer dan normaal. We bezorgen je pakket zo snel mogelijk.” / ENG “It's very busy. Please allow for slightly slower delivery times. We'll deliver your parcel as soon as we can.”
Explanation: This scan observation indicates that a shipment that has been handed over at a PostNL drop-off point is not yet sorted and is currently in stock waiting for the first sorting scan.
We recommend to treat this observation as an indication that the parcel is delayed.
T&T status code / Observation: V06
Description: NL “Door drukte duurt de bezorging wat langer dan normaal. We bezorgen je pakket zo snel mogelijk.” / ENG “It's very busy. Please allow for slightly slower delivery times. We'll deliver your parcel as soon as we can.”
Explanation: This scan observation also indicates a delay. It did not receive its first sorting scan yet. This scan often occurs during peak periods. We recommend to treat this observation as an indication that the parcel is delayed.
How can you act on this change?
Prepare for this change by storing the codes (G03 and V06) and corresponding descriptions in the appropriate (harmonization or definition) table. Check the complete list of PostNL T&T status codes. In addition, make sure that applications that convert the scan observations to information for your business processes recognize these scans and provide the correct information.
[25-06-2024] Scheduled downtime Send & Track-API's
Please be informed that all PostNL-API's necessary for the creation of shipping-labels and pre-alerts will be unavailable due to scheduled maintenance between 01:00 AM and 02:00 AM (CET) on July 2nd. Be advised that this also applies to the Shipment-API.
[30-05-2024] Scheduled downtime Send & Track-API's
Please be informed that all PostNL-API's necessary for the creation of shipping-labels and pre-alerts will be unavailable due to scheduled maintenance between 01:00 AM and 01:30 AM on June 25th. Be advised that this also applies to the Shipment-API.
We apologize for any inconvenience this may cause.
[21-05-2024] Maintenance Notification for Labelling and Shipment API
On Wednesday, May 22, from 21:00-22:00, both the Labelling and Shipment APIs will undergo maintenance to address the incorrect handling of multiple shipment objects in one API-call. No downtime is expected for either service.
[02-05-2024] New validation process business reply numbers
On June 18, 2024, we will implement a new validation process for business reply numbers related to product codes 2285 and 3285, which will affect return shipments. This update is crucial to ensure accurate preannouncements and improve both billing and product quality.
Validation Activation:
- For product code 2285, only business reply numbers can be used as recipient addresses.
- For product code 3285, business reply numbers cannot be used as recipient addresses.
Impact:
- This change has no impact if preannouncements are correct
- Incorrect preannouncements will trigger an error.
- Affected shipments will not receive a label or be pre-notified.
Required Actions:
If needed, adjust the recipient's address in AddressType 01 to align with the correct product code requirements.
Support:
- For API adjustments or testing, contact us via the support form with "Business reply number validation" in the subject.
- If you would like advice on which product codes or return options to use, please contact your account manager.
[28-02-2024] Upgrade generation of shipping labels
Per 10 april 09:00 AM, the application for the generation of shipping labels will be upgraded. As a result, Printertype-responses in the categy Zebra|Generic ZPL II have adjustments in the buildup of the ZPL-code. Users of this printer type output are advised to evaluate the ZPL-output on compatibility with application(s) and/or hardware.
Adjustments to the ZPL output are as follows:
- The resolution command (^JM) is now set within a label format (^XA, ^XZ block)
- The documentation command (^FX) containing the form name is no longer generated.
- The ZPL header value in the default configuration file was changed to an empty value instead of "^MMT". If the original value (^MMT) is used, it is replaced by "^XA^MMT^XZ" to match the ZPL reference.
- Some ZPL commands like (^LS, ^LT etc.) are now generated only once before the first label and no longer on every label.
The new Zebra|Generic output-types are retrievable via the sandbox-environment of either Labelling- or Shipment-API.
[09-01-2024] Update API-management portal
Per January 10th, the API-management portal has been deactivated and can no longer be used for retrieving your API-credentials. Please contact Chanel integrations via the support form and provide your customer number and username of the API-management portal for assistance.
If you use the API key for Data Solutions and you are unable to locate your API key in the module 'Manage API keys', please reach out to our support team at datasolutions@postnl.nl.
Changelog 2023
It's time to take action if you are still using a version lower than 5.0.0 of the PostNL plugin for WooCommerce. The outdated versions will be disabled starting from November 1, 2023. How do I install the latest version?
First, close your existing orders. Please close all existing orders before installing the new plugin. If this step is omitted, shipping labels for these orders will not be generated. If you forget to do this, you can manually create the shipping labels later through your My PostNL environment.
The installation steps for the latest version can be found in the guide. Make sure to have your PostNL customer number and API details ready beforehand. Please note that the API details are different from what you are currently using. You can find these in your My PostNL environment under "My Account > Manage API."
Need assistance? Feel free to ask your question via the support form
You will receive a response within two business days.
On 01-01-2024 PostNL will launch a new product portfolio for sending from Belgium to the Netherlands. For customers this implies some technical changes in confirming shipments. These changes must be implemented between August 1st 2023 and January 1st 2024. During this period both the old and the new portfolio can be use
For more information, please visit this page where you will find all technical instructions for each of our IT connections.
PostNL has introduced a new portal for technical API documentation. This new website is based on the OpenAPI specification of our collection of API's for e-commerce processes. Via https://docs.api.postnl.nl you can find an easy-to-navigate documentation portal extended with up-to-date API specifications, references and code samples.
From now on PostNl offers a three-panel, responsive layout for the technical documentation:
• The left panel contains a search bar and navigation menu.
• The central panel contains the documentation.
• The right panel contains request and response examples.
The current Developer Portal will still be the entry point for information about the APIs for commercial information. Commercial information such as explanation of API usage and Use cases are still listed here. On the updated documentation pages, developers are now redirected to the technical documentation.
The renewed international product portfolio is available per the 1st January 2023. This makes it possible to select additional services per product. The choice of services offers you extra flexibility. You can easily choose per item which service you require. Do you send valuable items? Then you can choose to send the item with an insurance. Or do you prefer a cheaper option? Simply turn off the proof of delivery (signature) for that item.
New product codes have been added and the ‘old’ product codes can still be used until further notice. The renewed International product portfolio has been added to the responses of the most recent versions of the Shipping and Labelling API. Please note preferable method is via REST (JSON).
Take a look at the Productinformation | Parcel EU, Parcel Non EU and International Mail & Packets of the API’s for more information. Example requests are also available in the postman collection.More information about the portfolio can be found on our website
Changelog 2022
PostNL introduces sustainable delivery options. Today, more and more consumers find sustainable delivery important. By using our Delivery Options API’s you can show customers when their parcel can be delivered sustainably – right in the checkout of your webshop. That way, your customers can make a conscious choice for green delivery.
This sustainable options has been added to the responses of the most recent versions of the Checkout, Location and Timeframe API. Please note that this is only available in REST (JSON).
Take a look at the Documentation | Guidelines pages of the API’s for more information.
THE PLANNED DEPLOYMENT OF JULY 28 WAS CANCELLED AND POSTPONED TO AUGUST 18.
PostNL will improve the backend service of the Labelling 2.1 API. Though customers should not experience any service interrupting changes, this could affect custom implementations.
Our current backend returns plain ZPL code, which allowed for the manipulation of the ZPL code. Though this was not a functionality supported by PostNL, we have found that there are some customers who do this. The new backend returns the label as an image, rather than sending separate fields and codes, which means previously used manipulations of the ZPL output is no longer supported. This is done so that there is a more general adoption of different Zebra printers. Previously we needed to have separate drivers for different printers, this is no longer needed.
Due to the fact that we support special characters (UTF-8) and some technical reasons, the size of the labels has increased.
The updated backend service is already active in our test environment (and in the Labelling 2.2 and Shipping v1 version). If you are not sure whether this affects your PostNL integration, you can test this in the sandbox environment.
The updated shipments method returns all the updated statuses for a particular customer number in a specific period. Lately, we are increasingly confronted with the incorrect use of this method, which affects the overall performance of our platform and the performance of the API users.
It is best practice to request the updated statuses for a particular customer number in windows of 15 minutes. If needed, you can increase or decrease the frequency. For a useful result and a better performance, the maximum time window is 1 day. It is advisable to request a maximum period of 1 day.
To truncate search queries to the Shippingstatus API, our development team change to return an error if the requested time range exceed the maximum time window of 2 days.
PostNL stops its food network. The market has developed differently than expected, so PostNL is closing the network.
The productcodes are no longer displayed at the Products page.
As of April 1st 2022 the International product ‘Parcels Non EU – combilabel’ productcode 4947 should no longer be used. Shipments to destinations outside the EU can be send via the product ‘Parcels non EU – Single label’ productcode 4945.
Benefits of the ‘Parcels non EU – single label’ product are that it contains a single Internationally recognized S10 barcode. Instead of an S10 barcode and a domestic 3S barcode. This makes the API request easier because only the S10 barcode is sufficient for requesting tracking, labels and the use of shippingstatus webservice. A single barcode on an item improves quality and the tracking of International shipments.
For more information contact your Account Manager.
Changelog 2021
-
Changelog 2020
As of January 1st, 2021, we have a renewed product portfolio for parcels shipping to Belgium. If you are using any of the Parcels EU product codes for sending to Belgium, change the product code for shipments to Belgium to a Parcels Netherlands-Belgium product code in your confirming and/or labelling requests.
Please make sure you use the Parcels Netherlands-Belgium before January 1st, 2022. As of the 1st of May pre-announcements on the old product codes (4944, 4940, 4932, 4938, 4950, 4952, 4985, 4993 and 4996) for destination Belgium trigger a surcharge for pre-announcing incorrectly.
For more information, please visit this page where you will find all technical instructions for each of our IT connections.
Brexit is about to happen, which will impact postal and parcel movements towards the United Kingdom (UK). We would like to inform you on this, since there are technical changes required to keep on servicing our mutual customers.
From January 1, 2021, free movement of goods between the UK and the Netherlands will be restricted, and a customs declaration will be required. Via PostNL you will be able to digitally prepare shipments via the same method as currently is available for Parcels towards a non-EU destination.
The UK will be covered by our Parcel non-EU product after Brexit. For Packets, the product code will remain the same.
Technical changes are described on our Developer Center. As time moves on, Brexit impact becomes more clear and we will update our Developer Center accordingly. Please check the Brexit page.
From May 18 the EU countries Malta, Cyprus and Croatia will be classified as EU countries. This change takes place in our systems so if you have an PostNL integration you have to change this in your (shipping) system.
As of May 18th, Croatia, Cyprus and Malta will be covered by product 4944 (Parcels EU – formerly known as EPS), instead of 4945 (Parcels non-EU – formerly known as Globalpack). Label requests via API for these countries dated May 18th and later will result in an error.
A letter from the receiving sorting center will be printed on the label of Mailbox parcels (Brievenbuspakjes). In this way, customers and PostNL employees within the operation can more quickly see to which sorting center the package should be sent.
The letter appears on the label of you use the Labelling 2.2 or Shipping v1 API. If you are not yet using one of this webservices, the advise is to update/upgrade as soon as possible.
Letter A Amsterdam
Letter R Rotterdam
Letter H 's Hertogen Bosch
Letter N Nieuwegein
Letter Z Zwolle
-An validation has been added on the Shipment.Customs.Content.Content.Weight attribute. According to the documentation this already had to be an integer; this is now being enforced.
-For International shipments (EU and Rest of Word), a validation for a maximum weight in the Shipment.Dimension.Weight attirbute has been added. This is now at 999 kg for now. This can be adjusted in the future to guarantee that we can process the shipments.
Changelog 2019
It will soon no longer be possible to use the Cash on Delivery product codes. PostNL has decided to stop the cash on delivery service (rembours) in the Netherlands and Belgium from January 1, 2020.
The following product codes have been removed from the Product documentation page:
3086 COD
3091 COD + Extra cover
3093 COD + Return when not home
3097 COD + Extra cover + Return when not home
Belgium productcodes
4964 Belgium COD + Return when not home
4966 Belgium COD + Extra cover + Return when not home
PostNL has created its own retail network in Belgium. The cooperation with Kariboo therefore will be canceled from 1 December. From this date, no Kariboo points will be returned in the Location API response.The Kariboo network code (LN-01) can therefore no longer be used in the Labeling and Confirming API. The network code (DownPartnerID for Labelling API request) for Belgium will be PNPBE-01 from now on.
PostNL is sending technical information nowadays. With this bi monthly newsletter PostNL inform tech savvy customers through API updates, integrated services, Tips & Tricks, new functions, plugins and partner channels. Also useful information about new functionalities in MyPostnl and the Developer Center can be read in this newsletters.
You can subscribe here for this newsletter.
Archive newsletter:
June 2019
Augustus 2019
A beta version of the Check-out API is released. Combining the existing Timeframe, DeliveryDate, and Location APIs, it allows for quick and easy implementation of the PostNL delivery options while also reducing the risk of errors creeping in. For more on the new API, head over to the Checkout API.
Unfortunately the delivery option Early Morning Pickup Points is no longer viable. This delivery option (code PGE) is not an option anymore in the Checkout and Location API. This option will therefore disappear completely from 1 October 2019.
The option "Pick up at a PostNL location' remains unchanged as a service.
From now on it is temporarily no longer possible to offer Evening delivery in Belgium. This delivery option is not an option anymore in the Checkout, Deliverdate and Timeframes API's and therefore not be shown in this API responses.
We will inform you in time when the delivery option is reactivated.
From now on it is possible to run Parcels API Collection(s) directly in the Postman application. Postman helps you test and implement the Parcels API’s faster. The collections contains SOAP and JSON requests, are grouped together and organized into folders. The Postman collections are subdivided into the following groups: All, Shipping, Delivery Options and Track & Trace.
A new way of confirming the product Pickup Basic (Afhaalservice Basis) has been introduced. The new way of confirming is live on the 1st of June. The currrent way of confirming can be used until the 1st of July.
It is a small adjustment, you can find the new product specifications and see the guidelines of the Confirming API.
A new version of the Shippingstatus API (v2) has been introduced. This version is only available in REST (JSON).
The method Updatedshipments has been added to the interface; this method returns the updated statuses for a particular customer number.
New versions of the Labelling (v2.2) and Confirming (v2) have been introduced. Please check the Versioning paragraphs of the API's to see what have been changed compared to the previous versions.
A new API has been introduced to validate address data while it is entered.
Free* API for use in webshop checkout.
Please check the documentation for more information.
*Only free of charge for PostNL Parcels contract customers.
A new Belgium retailnetwork has been added to the services. The attribute DownPartnerID for Pickup at PostNL location can now contain the value PNPBE-01 in addition to the already existing code LN-01. Please check the Labelling and/or Confirming API documentation for more information.