Why use the shipping API
Generate shipping labels
To produce labels for domestic use (in The Netherlands and Belgium) as well as for Parcels EU and Parcels Non-EU (worldwide).
_tcm10-207969.svg)
Integrate in your own infrastructure
You can integrate this service in your IT infrastructure immediately after completed transactions in your checkout.
Confirming parcels
To create a label and the confirmation (optional) toward PostNL and match the receiver and label.
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.
Integrate new version
We are renewing and improving our API portfolio.
The new API versions will replace the older ones, improving performance and making integration simpler and more scalable. We are also making them safer and more stable with predictable updates. This way, you can enjoy our latest products and services worry-free, today and in the future.
The new APIs will be rolled out in phases, starting with the new Shipment V4 and Return V4 API. Right now, this API is available only to a selected group of PostNL customers. If you haven’t received an invite yet, you’re not eligible just yet — but don’t worry. As we continue to add new features and improve the experience, more customers will be invited to join. Thanks for bearing with us – we’re excited to rollout the API to a broader audience soon!
You can already start exploring the product, functionalities, and see which ones fit your needs.
Guidelines
Learn more about the Shipping API guidelines.
All-in-one Shipping API
This API combines the functionality of the existing Barcode, Labelling, Confirmation and Easy Return APIs. Integration of the Barcode API lets you generate unique barcodes for each shipment whilst cutting down on the number of API requests.
Shipping labels
The label that are send to you is not suited for scaling, for the measures of the label are carefully designed to ease the parcel through our process.
Barcodes
It is possible to send a barcode in the request. But if you leave the barcode out of your request an unique barcode will be generated automatically.
NOTE: This is not possible for additional barcodes in Label in the box (return barcode), multi-collo and Combilabels ‘Parcels non EU‘ with productcode 4945 (downpartner barcode) shipment requests. And also International Mail & Packet products (PEPS) barcodes cannot be generated automatically by using this service.
Please check the Barcode API page for specific barcode guidelines.
Confirmation
This API contains the possibility to create a label and the PostNL confirmation. This service sends the confirmation to the PostNL systems and upon receiving the confirmation, the service sends back a filled in label to print and to stick on the parcel.
With the Confirm boolean in the request (true of false), you can determine if you want to confirm the shipment in the same call or not.
Print quality for shipping labels
Parcels are sometimes delayed as a result of poorly-printed shipping labels, because we are unable to scan the barcode. To prevent this, we ask to pay close attention to the print quality of your labels. That way, we can apply smarter sorting to your parcels, deliver faster and achieve more satisfied customers.
Please check this link for more information.
Error handling
We would like to stress the need for a suitable error handling implementation on your side. If somehow, an error is received at your end upon sending your confirmation, this means that we could not process the information correctly and the successful delivery of the parcel is in jeopardy. We strive to return the error message with as much detail as possible so you can take proper action in order to improve the information about the parcel and retry.
Error codes have been specified in the API Generic document. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in API.
This field can be used in case the values of Street, HouseNr and HouseNrExt can’t be mapped separately before calling the API.
Printertypes
A printer type must be specified in the request. The API is capable of generating a wide range of output format. See the printer types below for the possible values. Please choose the type that fits best with your local printing situation.
GraphicFile|GIF 200, 300 and 600 dpi
GraphicFile|JPG 200,300 and 600 dpi
GraphicFile|PDF
GraphicFile|PDF|MergeA, MergeB, MergeC and MergeD
Zebra|Generic ZPL II 200, 300 and 600 dpi *
* It is not recommended to send .pdf files/labels directly to a Zebra printer If you want to send it directly to your Zebra printer, please use .gif files or the native (generic) zpl printer type.
The Label type helps you to determine what document is returned. In most cases, only a Label is returned. The following label types are possible:
| Labeltype | Description |
|---|---|
| Label (A6) | normal shipping label for all shipments except for Parcels Non-EU |
| BusPakjeExtra (A6) | shipping label for parcels that fit in a mailbox |
| CODcard (Kabinet (21 x 10,16 cm) | COD card as required for Dutch domestic COD shipments |
| CN23 form (A5) | customs form for Parcels Non-EU shipments |
| CP71 form (A5) | customs form for Parcels Non-EU shipments |
| Commercialinvoice (A4) |
commercial invoice for Parcels Non-EU shipments |
| Return Label (A6) |
normal shipping label for reverse logistics |
Productcode 4945:
ShipmentType parameter Gift or Documents: CN23 / CP71
ShipmentType parameter Commercial Goods, Commercial Sample or Returned Goods: CN23/ CP71/ CommercialInvoice
Address type
PostNL internal applications validate the receiver address. In case the spelling of addresses should be different according to our PostNL information, the address details will be corrected. This can be noticed in Track & Trace.
The API will not add address details. Street and City fields will only be printed when they are in the call towards the Shipping or Labelling API.
The element Address type is a code in the request. Possible values are:
| Code | Description |
|---|---|
| 01 | Receiver |
| 02 | Sender |
| 03 | Alternative sender address |
| 04 | Collection address |
| 08 | Return address* |
| 09 | Delivery address (for use with Pick up at PostNL location) |
* When using the ‘label in the box return label’, it is mandatory to use an Antwoordnummer in AddressType 08. This cannot be a regular address.
Remarks:
Within the CustomerType, only AddressType 02 can be used. This Type can also be placed in the ShipmentType.
Within the ShipmentType, at least ShipmentType with 01 is required.
Shipment type
The element Shipment type is a code in the request. Possbile values are:
| Code | Description |
|---|---|
| 01 | Receiver |
| 02 | Sender (if not in Customer/Address) |
| 03 | Alternative sender address |
| 04 | Collection address |
| 08 | Return address* |
| 09 | Delivery address (for use with Pickup at PostNL location) |
* When using the ‘label in the box return label’, it is mandatory to use a Antwoordnummer in AddressType 08. This cannot be a regular address.
The following rules apply:
If there is no Address specified with AddressType = 02, the data from Customer/Address will be added to the list as AddressType 02. If there is no Customer/Address, the message will be rejected.
An Address with AddressType = 02 can be specified. In this case, no Customer/Address has to be specified.
At least one other AddressType must be specified, other than AddressType 02. In most cases this will be AddressType 01, the receiver address.
Contact type has the elements Email, SMSNr and TelNr. These fields have a dependency with each other. At least one of these three fields must be filled mandatory for certain products/ product codes (e.g. Evening/Sameday delivery, Pickup at PostNL location). Two or three can be filled as well.
| Code | Description |
| 01 | Receiver |
| 02 | Sender |
Remark: Please add the e-mail address of the receiver to improve the Mijn PostNL experience of your customer.
Multi-collo
Each request contains a single parcel. This parcel can be (part of) a single shipment or can be part of a multi-collo shipment. Each parcel in a multi-collo shipment must be sent in a separate request towards the API.
For shipments within the Netherlands domestic, Belgium domestic, Netherlands to Belgium and Belgium to Netherlands, multi collo shipments can be created. Using the API, this can be done as follows:
- Create a separate request per parcel to retrieve a label or to confirm the shipment (or both at once).
- Connect the parcels by using the Group type in each request. Mention the amount of parcels in the shipment (GroupCount), the number of the specific Parcel (GroupSequence) and the main barcode of the shipment (MainBarcode) and specify Multicollo as the GroupType (GroupType 03).
- Every parcel in the multi collo shipment has to have its own, unique barcode.
For Extra@Home and Cargo shipments, the requests cannot be done separately for multicollo shipments. Multi collo shipments must be confirmed in one joint request.
Multi collo shipments is not available for EU, Mail packages and returns.
Multiple shipments
Multiple shipments can be sent in one request. To this end the Shipment field has been replaced by a Shipments field, which contains a list of Shipment elements. The response has also been modified. Instead of a ResponseShipment element, the response now consists of a GenerateLabelResponse element, which has a ResponseShipments field containing multiple ResponseShipment elements.
A maximum of four Shipment elements can be included in the Shipments field. When sending multiple signature images, keep in mind that the maximum size for the entire request is 200 KB.
You can use this functionality with the GraphicFile|PDF|Merge printer types to generate one label document containing multiple labels. These “merged label” documents can be found in the MergedLabels response field.
If you want to send only one shipment, you have to specify the Shipments element containing one Shipment.
Multiple label printing
It is possible to generate multiple labels at once, and have these labels printed on a single A4-sheet.
In order to use this functionality, you must select a different PrinterType. The PrinterType chosen determines the starting position of the label that is generated first. Below are the four printertypes that will produce an A4 sheet with multiple labels
GraphicFile|PDF|MergeA
GraphicFile|PDF|MergeB
GraphicFile|PDF|MergeC
GraphicFile|PDF|MergeD
In the figure below, the label starting position is shown for each type.
MergeA MergeB
MergeC MergeD
When a Merge type is chosen, the labels that follow are automatically printed on the next position. Note that four labels can be printed at once using this method, so you are always able to fill a complete A4 sheet.
Limitations
The following applies to the merge functionality described above:
MergeA-D cannot be used for labels which are not 10x15 cm
MergeA-D cannot be used for combilabels
MergeA-D cannot be used for COD-products, due to the COD-card being printed.
You can request up to four labels at once.