Changelog

Due to changing regulations from the UPU (Universal Postal Union) from 2026 onwards it’s no longer allowed to ship registered packets and letterbox parcels containing goods to destinations outside of the Netherlands. 

This concerns the following product codes:

6906
6908 

Both products will bel continued by PostNL as a tracked service including insurance up to 50 euro. 

Technical impact: 

In order to comply with the new regulations and still use the same product code we ask customers to do the following. 

Currently a registered barcode (starting with RI) is required for these international packets. This must be changed to a tracked barcode (starting with LA). 

To do so you must change the parameter “Type” in the Barcode API from “RI” to “LA” in your barcode request. The rest of the barcode request can remain the same. 

Example of a correct barcode request: https://api.postnl.nl/shipment/v1_1/barcode?CustomerCode=ABCD&CustomerNumber=11223344&Type=LA&Serie=00000000-99999999&Range=NL 

The new barcode can be used with immediate effect. It’s recommended to change your configuration as soon as possible as countries may decide not to process packets with RI barcodes anymore in 2026. 

For registered international letters not containing goods (product code 6418) RI barcodes must still be used.

As of January 2026, the module where you manage your API keys will switch to a new portal. Make sure to store your current API key safely, if you haven’t done so yet, as it will no longer be visible after this date. In the new portal, you’ll be able to request and manage your API keys for our future-proof APIs.

Due to the new regulations in the United States, it is temporarily not possible to send parcels and packets to the United States via PostNL. We are working on a solution. Business mail (documents in an envelope) can still be sent. 

[18-08-2025] Urgent: Changing Regulations for shipping goods to the United States

As of August 29, increased import duties and taxes must be paid for shipments to the US. Following this change, it becomes even more important to provide correct customs data when pre-registering shipments.

Validation change per August 22th

In preparation for this change, PostNL requires from August 22 onwardsthat HS codes (HSTariffNr) must contain 10 digits for shipments to the US (CountryCode = US).

From August 22 onwards an error message will be returned if a HS-code is longer or shorter than 10 digits.

Valid HS codes can be found at: https://dataweb.usitc.gov/tariff/database

The US has threatened that high costs may be charged to the sender for incomplete customs declarations. Therefore, we strongly urge you to also pay close attention to the accuracy of other customs data, such as:

• The value of the goods
• A clear description of the goods
• The country of origin of the goods (This must be the country where the product was manufactured or substantially processed)

For other destinations outside the EU, the current rule remains that HS codes must contain 6-10 digits.

We are currently working on a new Delivery Duty Paid solution for the US. This might lead to additional requirements for destination US. We will keep you posted about this via our developer portal.

[11-06-2025] Action Required: Enforced ContactType Validation

Starting June 12, 2025, all versions of these APIs will enforce a validation rule allowing only one contact with type "01" in the Contacts object. If multiple "ContactType": "01" entries are sent, an error will be raised with either errorcode 34019 or 340209,

Action:
Review your integration and ensure only one "ContactType": "01" is included per shipment.

Support:
For questions or support, please contact the Channel Integrations team via: https://developer.postnl.nl/support/form/

We are renewing and improving our API portfolio to make your integration with PostNL easier, more secure, and future-proof. These new versions improve performance, provide more consistency, and are better aligned with modern systems and data models. We’re also implementing API Life Cycle Management, making updates more predictable and easier to manage. The new APIs will be rolled out in phases. The Shipment API v4 and the all-new Returns API v4 will be the first, going live in May 2025.

Please be informed that the ERS products for our international return solutions will be unavailable on April due to scheduled maintenance between 07:00 AM and 11:00 AM on Tuesday April 29. Be advised that this applies for the ERS Portal & the ERS products via API.

We apologize for any inconvenience this may cause.

Starting March 13th, we are implementing technical upgrades for international shipments processed through our partner, DPD. These enhancements may result in different pre-alert error messages than those previously encountered. The error messages will indicate what the issue is.

Change:
From April 17, 2025, PostNL will update the Labelling-API, Confirming-API, and Shipment-API (all versions). Additional pre-announcements on barcodes that have received an acceptance scan (B01) will be rejected. Modifications to parcels already in process will no longer be possible.

Impact:

• Additional label creation: Once a parcel has received its first logistical scan by PostNL, no additional labels can be generated.
• Pre-announcement scheduling: Pre-alert modifications must be completed before handover to PostNL, as updates will no longer be allowed after an acceptance scan.

Action Required:

• Ensure all pre-announcements are completed
• Update integrations to prevent duplicate or late pre-alerts.

Support:
For questions or assistance, contact the Channel Integrations team via the support form.

As of February 2, Sunday Delivery and 08:00-09:00 Delivery are no longer available. On March 2, Today Delivery will also be discontinued. Affected APIs include Timeframe, Checkout, DeliveryDate, Labelling, Shipment, and Confirming.

From March 17, the parameters Sunday, 08:00-09:00, and Today will no longer be usable, and API calls with these will return an error. Update your integration to avoid disruptions.

Per January 1st, one extra observation scan is added to our Shipping Status API. The observation scan has to do with the new postal regulations in Germany we communicated about earlier. Per January 1st all items shipped to Germany with a weight higher than 10KG should include a weight icon on the label. The icon placed on the label is based on the pre-announced weight. If you ship an item of 12KG, but pre-announce it with a weight lower than 10KG or no weight at all, it’s necessary for us to relabel the parcel again before shipping it to Germany. As a result of relabeling the partner barcode on the combilabel will be replaced as well. The original partner barcode becomes obsolete.

To prevent this behavior we strongly recommend to fill in a correct weight when pre-announcing shipments to Germany. If you’re not able to do so (and do ship items above 10KG) we strongly recommend not to build any (track and trace) logic on the partner barcode (DownPartnerBarcode).

T&T status code / Observation: P12

Description: NL: “Onjuiste gegevens, labelcorrectie volgt. Gebruik alleen de originele (3S) track & trace-code.” / ENG “Shipment to be relabeled due to incorrect data. Please use the original (3S) tracking code only.”

Explanation: This scan observation indicates that the international combilabel and partner barcode will be replaced.

We recommend treating this observation as an indicator to correctly pre-announce weights in the future.

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.

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. 

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.

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.

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.

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.

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.

Per January 10^th, 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.