The Shipping API combines the functionality of the Labelling, Confirming, Barcode and Easy Return API’s. As of now you have an all-in-one API covering these functionalities, hence it is easier to implement the PostNL Shipping Services and overhead is reduced in requesting these services.
All the necessary information for implementing this API.
Why use the Shipping API
This API combines creating a label and the confirmation (optional) toward PostNL. In this way, the information we receive and the label always matches. This guarantees a smoother process in distribution.
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.
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.
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.
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.
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.
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.
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
In the figure below, the label starting position is shown for each type.
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.
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.
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|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:
|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|
commercial invoice for Parcels Non-EU shipments
|Return Label (A6)|
normal shipping label for reverse logistics
ShipmentType parameter Gift or Documents: CN23 / CP71
ShipmentType parameter Commercial Goods, Commercial Sample or Returned Goods: CN23/ CP71/ CommercialInvoice
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:
|03||Alternative sender 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.
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.
The element Shipment type is a code in the request. Possbile values are:
|02||Sender (if not in Customer/Address)|
|03||Alternative sender 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.
Remark: Please add the e-mail address of the receiver to improve the Mijn PostNL experience of your customer.