Shipping

Documentation

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.

Development

All the necessary information for implementing this API.

.

Go to Technical documentation https://docs.api.postnl.nl

Why use the Shipping API

Generate shipping labels

This service provides you the possibility to produce labels for domestic use (in The Netherlands and Belgium) as well for Parcels EU and Parcels Non-EU (worldwide).

Integration

You can integrate this service in your IT- infrastructure immediately after completed transactions in your checkout, for this eases the whole process thereafter.

Confirming parcels
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.

Get started

Request your (Sandbox) API Key and start using the API.

As soon as you have an API key, it is recommended to run our Postman collectio ns. Here you can find code examples of the various services and products we offer. This makes implementing the APIs much easier.

Start using the 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.

Request size

The total request can have a maximum size of 200KB. Larger requests will not be accepted by the server for performance reasons. Requests that exceed this limit will not return a label, but a HTTP 404 error.

Easy Return Service (ERS)

Previously a standalone API but integrated in this service to growing demand for international returns. Productcode 4910 can be used in the ProductCodeDelivery attribute.

Destination EU / Rest of World

The Customs type is mandatory for ‘Parcels non-EU” (Rest of World) shipments and recommended for shipments with destination EU and not allowed for any other shipment types.

Street, HouseNr and HouseNrExt

The element StreetHouseNrExt is a combination of Street, HouseNr and HouseNrExt. This field has a dependency with the field Street. One of both fields must be filled mandatory.
This field can be used in case the values of Street, HouseNr and HouseNrExt can’t be mapped separately before calling the API.

The API will calculate a split of street name, house number and extension for you, and will afterwards use the split values. This might result in incorrect behavior for which PostNL can’t be held liable. Content in this field must be in the described order or otherwise the conversion will not work and place all values in the Street field.

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, 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.

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.

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.

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.

Label types
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
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.