Labelling

Documentation

In our distribution process, shipping labels are used to guide the parcels on its way to delivery and PostNL rely on the information on the labels . This makes it a vital step in the journey of the parcel from sender to receiver.

Why use the Labelling 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 toward PostNL (optional). 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 collections. 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

Development

On this page you will find all the necessary information for implementing this API.
Please check the Guidelines for useful information.
Descriptions, formats and examples of the API attributes are also very useful to look at.

Method

Call details

Versioning

Guidelines

Code example

Request example:
 
curl --location --request
POST 'https://api-sandbox.postnl.nl/shipment/v2_2/label' \
--header 'Content-Type: application/json' \
--header 'apikey: ***' \
--data-raw '{
"Customer": {
 "Address": {
   "AddressType": "02",
   "City": "Den Haag",
   "CompanyName": "PostNL",
   "Countrycode": "NL",
   "HouseNr": "3",
   "Street": "Waldorpstraat",
   "Zipcode": "2521CA"
 },
 "CollectionLocation": "123456",
 "ContactPerson": "Janssen",
 "CustomerCode": "DEVC",
 "CustomerNumber": "11223344",
 "Email": "email@company.com",
 "Name": "Janssen"
},
"Message": {
 "MessageID": "1",
 "MessageTimeStamp": "08-09-2022 12:00:00",
 "Printertype": "GraphicFile|PDF"
},
"Shipments": {
 "Addresses": [
   {
     "AddressType": "01",
     "Building": "",
     "City": "Utrecht",
     "Countrycode": "NL",
     "FirstName": "Peter",
     "HouseNr": "9",
     "HouseNrExt": "a bis",
     "Name": "de Ruiter",
     "Street": "Bilderdijkstraat",
     "Zipcode": "3532VA"
   }
 ],
 "Barcode": "3SDEVC520422911",
 "Contacts": [
   {
     "ContactType": "01",
     "Email": "receiver@email.com",
     "SMSNr": "+31612345678",
     "TelNr": "+31301234567"
   }
 ],
 "Dimension": {
   "Weight": "2000"
 },
 "ProductCodeDelivery": "3085"
    }
}
 
Response: 
 
{
    "MergedLabels": [],
    "ResponseShipments": [
        {
            "Barcode": "3SDEVC520422911",
            "Errors": [],
            "Warnings": [],
            "Labels": [
                {
                    "Content":[TRUNCATED BASE64 STRING] <"JVBERi0xLjMKJeLjz9
               MKNSAwIG9iago8PAovQ29udGVudHMgNiAwIFIKL01lZGl
               hQm94IFsgMCAwIDQxOS41MyAyOTcuNjQgXQovUGFyZW50IDQgM
               CBSCi9SZXNvdXJjZXMgNyAwIFIKL1R5cGUgL1BhZ2UKPj4KZW5kb2JqCjYgMC
               BvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxNjAyCj4+
               CnN0cmVhbQp4nLVYy25bRwzd6yvmBzzlYx4cIOgiQJK1WwFdFF3YlhSgixbJ
               pr/fw/uQrq2bGXdRyLYepvg4JM+ +XQo+PgpzdGFydHhyZWYKMjM
               3NDYKJSVFT0YK",
                    "Labeltype": "Label",
                    "OutputType": "PDF"
                }
            ],
            "ProductCodeDelivery": "3385"
          }
    ]
}

Request Labelling API

CustomerType

AttributeMandatoryFormatDescriptionExample
AddressO-MAddress typeSee Address type (XmlElement is Address)
Address 02 is mandatory. It can either be placed in the Customer segment or in the Shipment segment.
Note that if you put it in the Shipment segment, it should go into all Shipment segments.
 
CollectionLocationMStringCode of delivery location at PostNL Pakketten123456
ContactPersonOStringName of customer contact personJanssen
CustomerCodeMString [1-4]Customer code as known at PostNL PakkettenABCD
CustomerNumberMInteger [1-8]Customer number as known at PostNL Pakketten1234567
EmailOString [0-50]E-mail address of customerjanssen@company.com
NameOString [0-35]Customer nameJanssen 

LabelSignature type

AttributeMandatoryFormatDescriptionExample
 OBase64

GIF image of the signature, max size: 280x60 mm (1058x226 pixels). As a base64 encoded string. This can be used to automatically sign the customs forms. The value of this element can have a maximum size of 65536 characters.

Larger requests will not be accepted by the server for performance reasons. Requests that exceed this limit will not return a validation error, but a HTTP 404 error.

 

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00
PrintertypeMString [1-35] Printer type that will be used to process the label, e.g. Zebra printer or PDF See Guidelines for the available printer types.GraphicFile|PDF

Shipments type

AttributeMandatoryFormatDescriptionExample
ShipmentMShipment typeList of 1 or more ShipmentType elements of a shipment. At least one shipment type is required. Shipments for validation or
confirmation.
 

Shipment type

AttributeMandatoryFormatDescriptionExample
AddressesMAddress typeList of 1 or more Address type elements
At least 1 address type is mandatory
 
Amounts0-MAmount typeList of 0 or more AmountType elements. An amount represents a value of the shipment.
Amount type 01 mandatory for COD-shipments, Amount type 02 mandatory for domestic insured shipments.
Amount type 04 mandatory for Commercial route China (productcode 4992)
Amount type 12 mandatory for Inco terms DDP Commercial route China (productcode 4992)
 
BarcodeMString [11-15] Barcode of the shipment. This is a unique value3SABCD6659149
CollectionTimeStampEndODatetime [19] Ending date/time of the collection of the shipment04-06-2016 17:00:00
CollectionTimeStampStartODatetime [19] Starting date/time of the collection of the shipment 04-06-2016 19:00:00
ContactsO-MContact typeOne or more ContactType elements belonging to a shipment
Mandatory in some cases. Please refer to the Guidelines
 
ContentO-MString [0-35] *Content of the shipment
Mandatory for Extra@Home shipments
Media player
CostCenterOString [0-35] Cost center of the shipment.
This value will appear on your invoice
SX-GT-66
CustomerOrderNumber OString [0-35] Order number of the customer. 8689242390
CustomsO-MCustoms typeThe Customs type is mandatory for Parcels Non-EU shipments and not allowed for any other shipment types. 
DeliveryAddressO-MInteger [2] Delivery address specification. This field is mandatory when AddressType on the Address is 09. 02
DeliveryTimestampEndO-MDatetime [19] Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments
THIS PRODUCT NO LONGER EXIST
04-06-2017 18:00:00
DeliveryTimestampStartO-MDatetime [19] Timestamp of the delivery used for Delivery on Demand (MyTime)
Mandatory for Delivery on Demand shipments
THIS PRODUCT NO LONGER EXIST
04-06-2017 16:00:00
DeliveryDateO-Mdatetime [19] 

Mandatory when using Mailbox Parcels (for generation of the coding rule) and delivery options like Evening/Morning/Sameday delivery etc. 

30-06-2016 12:00:00
DimensionMDimension typeDimension of a shipment.
See the dimension type.
 
DownPartnerBarcodeO-M String [0-35]Barcode of the downstream network partner of PostNL Pakketten.
CD123456785NL
DownPartnerIDO-M String [0-50]Identification of the downstream network partner of PostNL Pakketten.
Mandatory for Pickup at PostNl Location Belgium. Use the data from the Location API response; attribute RetailNetworkID 
PNPBE-01
DownPartnerLocationO-MString [0-10]Identification of the location of the downstream network partner of PostNL Pakketten.
BE0Q82
GroupsO-MGroup typeList of 0 or more Group types with data, grouping multiple shipments together.
Mandatory for multicollo shipments. Please see Guidelines (Multiple shipments) for more information.
 
IDExpirationO-MDate [10]Expiration date of the ID document.
Mandatory for ID Check products
05-06-2020
IDNumberO-MString [0-20]Document number of the ID document
Mandatory for ID Check products
4261103214
IDTypeO-MInteger [2]Type of the ID document.
Mandatory for ID Check products.
See Products for possible values
03
ProductCodeCollectOInteger [4]Second product code of a shipment3153
ProductCodeDeliveryMInteger [4]Product code of the shipment3085
ProductOptionsO-MProductOption typeProduct options for the shipment, mandatory for certain products, see the Products page of this webservice 
ReceiverDateOfBirthO-MDate [10]Date of birth
Mandatory for Age check products
10-12-1980
ReferenceO-MString [0-35] *Your own reference of the shipment. Mandatory for Extra@Home shipments; for E@H this is used to create your order number, so this should be unique for each request.2016014567
ReferenceCollectOString [0-35]Additional reference of the collect order of the shipment.6659150
RemarkOString [0-35]Remark of the shipment. Displayed on label, not used for data under GDPR.Fragile
ReturnBarcodeO-MString [11-15]

Return barcode of the shipment. PostNL will provide you with a separate customer code specifically for generating the returnBarcode.

Note: It is not possible to generate Label in the box labels with the 1.4 and 1.5 version. Please upgrade to the newest API version (or at least > 1.5) .

 

Mandatory for Label in the Box (return label) shipments.
3SABCD7762162
ReturnReferenceOString [0-35]Return reference of the shipment.112233

* To be sure that all the characters are visible on the label don’t use more than 20 characters.

Address type

AttributeMandatoryFormatDescriptionExample
AddressTypeMInteger [2]Type of the address. This is a code. You can find the possible values at Guidelines02
AreaOString [0-35]Area of the addressBeukenhorst
BuildingnameOString [0-35]Building name of the addressAA
CityMString [0-35] *City of the addressHoofddorp
CompanyNameO-MString [0-35] *This field has a dependency with the field Name. One of both fields must be filled mandatory; using both fields is also allowed.
Mandatory when AddressType is 09.
PostNL
CountrycodeMString [2]The ISO2 country codesNL
DepartmentOString [0-35]Send to specific department of a company.IT
DoorcodeOString [0-35]Door code of address123
FirstNameOString [0-35] *Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.Peter
FloorOString [0-35]Send to specific floor of a company.4
HouseNrO-MString [0-35]Mandatory for shipments to Benelux.
Max. length is 5 characters (only for Benelux addresses).
For Benelux addresses, this field should always be numeric.
42
HouseNrExtONL= String [0-6]
Outside of NL= String [0-35]
House number extensionA
NameO-MString [0-35] *Last name of person. This field has a dependency with the field CompanyName. One of both fields must be filled mandatory; using both fields is also allowed. Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer.de Ruiter
RegionOString [0-35]RegionNoord-Holland
RemarkOString [0-35]Remark of the shipment. Displayed on label, not used for data under GDPR.Fragile
StreetO-MString [0-95] *This field has a dependency with the field StreetHouseNrExt. One of both fields must be filled mandatory; using both fields is also allowed.Siriusdreef
StreetHouseNrExtO-MString [0-95]

Combination of Street, HouseNr and HouseNrExt. Please see Guidelines for the explanation

Siriusdreef 42 A
ZipcodeO-MString [0-10]Zipcode of the address. Mandatory for shipments to Benelux
Max length (NL) 6 characters, (BE;LU) 4 numeric characters.
2132WT

* It may happen that not all the characters will be shown on the label.

Amount type

 
AttributeMandatoryFormatDescriptionExample
AccountNameOString [0-35]Name of bank account ownerC. de Ruiter
AmountTypeMInteger [2]Amount type. This is a code. Possible values are: 02 = Insured value
04 mandatory for Commercial route China.
12 mandatory for Inco terms DDP Commercial route China.
01
BICO-MString [8-11]BIC number, optional for COD shipments (mandatory for bank account number other than originating in The Netherlands)RABONL2UXXX
CurrencyOString [3]Currency code according ISO 4217. E.g. EUREUR
IBANO- MString [15-31]IBAN bank account number, mandatory for COD shipments. Dutch IBAN numbers are 18 charactersNL00RABO0123456789
ReferenceOString [0-35]Personal payment reference1234-5678
TransactionNumberOString [0-35]Transaction number1234
ValueO-MDecimal [0-9]Money value in EUR (unless value Currency is specified for another currency). Value format (N6.2): #####0.00 (2 digits behind decimal dot)
Mandatory for COD, Insured products (with the exception of certain productcodes with a standard insured amount) and Commercial route China. For COD the Eurosign (€) is always required.

10.00

Contact type

AttributeMandatoryFormatDescriptionExample
ContactTypeMInteger [2]Type of the contact. This is a code. You can find the possible values at Guidelines01
EmailO-MString [0-50]Email address of the contact. Mandatory in some cases. Please see Guidelinesreceiver@gmail.com
SMSNrO-MString [10-17]Mobile phone number of the contact. Mandatory in some cases.0612345678
TelNrO-MString [10-17]Phone number of the contact.0612345678

Customs type

AttributeMandatoryFormatDescriptionExample
CertificateO-MBoolean [true/false]Possible values are true/false (no capitals allowed) Fill in if applicable, for specific items a export certificate is obliged, as proof that the item complies to the sanity regulations, more information. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)true
CertificateNrO-MString [0-35]Mandatory when Certificate is true.NR112233
ContentMContent typeThis section is mandatory (minimum once, maximum 5) 
CurrencyMString [3]Currency code, only EUR, GBD, USD and CNY are allowed.EUR

HandleAsNonDeliverableMBoolean [true/false]Determines what to do when the Parcel shipment cannot be delivered the first time (if this is set to true, the parcel shipment will be returned after the first failed attempt)false
InvoiceO-MBoolean [true/false]Possible values are true/false (no capitals allowed)
Fill in the invoice number of the shipment. For a faster customs clearing process apply the invoice on the outside of the shipment. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)
true
InvoiceNrO-MString [0-35]Mandatory when Invoice is true.22334455
LicenseO-MBoolean [true/false]Possible values are true/false (no capitals allowed) Fill in if applicable. Mandatory for Parcel shipments in the category type Commercial Goods, Commercial Sample and Returned Goods (Certificate, Invoice or License; at least 1 out of 3 must be selected)true
LicenseNrO-MString [0-35]Mandatory when License is true11223344

ShipmentTypeMString [1-35]Type of shipment, possible values: Gift, Documents, Commercial Goods, Commercial Sample, Returned GoodsCommercial Goods
TrustedShipperIDOString [0-50]Use only when available.
Depending on the destination with this ID the customs process can be faster. Only fill in this customs reference number if the sender is registrated as Trusted Shipper in the country of destination
1234
ImporterReferenceCodeOString [0-50]

Fill in a Tax Code or VAT number or Importer code. Depending on the destination with this reference the customs process can be faster

567
TransactionCodeO-MString [0-50]

Code and accompanying description according to UPU List 136: “Item nature indication codes” (link). Most common codes are shown below for your reference.
TransactionCode / TransactionDecription
11                        Sale of goods
21                        Returned goods
31                        Gift
32                        Commercial sample
91                        Documents

11
TransactionDescriptionO-MString [0-50]

Transaction description
See TransactionCode description above

Sale of goods

Content type

AttributeMandatoryFormatDescriptionExample
DescriptionMString [1-35]Clear description of the content of the item in English (description of goods)Powdered milk
QuantityMInteger [1-4]Fill in the total of the item(s)2
WeightMInteger [1-20]Fill in the weight of the item(s) in gram (gr)2600
ValueMDecimal [1-9]Fill in the value of the item(s)20.00
HSTariffNrMString [6]Specify every item with the standard HS commodity code (HS-code), more information100878
CountryOfOriginMString [2]Fill in the code of the country where the item was produced (ISO-code), more informationNL

Dimension type

AttributeMandatoryFormatDescriptionExample
WeightMInteger [0-20]Weight of the shipment in grams
Approximate weight suffices
4300
LengthOInteger [0-20]The longest side of the shipment in millimeters (mm).700
WidthOInteger [0-20]The second longest side of the shipment in millimeters (mm).500
HeightOInteger [0-20]The shortest side of the shipment in millimeters (mm).300
VolumeO-MInteger [0-20]Volume of the shipment in centimeters (cm3).
Mandatory for E@H-products
30000

Note: Length, Width, Height values are about the order of the size and need to be filled in from the longest to the shortest value. For example: shipment’s official height is 700mm, width 500mm, length 300m. The longest side (highest value) of 700mm needs to be entered at Length. Width value becomes 500mm, Height value: 300mm (the lowest). Entering the dimensions in the wrong order may result in incorrect shipping labels and longer delivery times. The maximum dimensions can be found in your PostNL contract.

Group type

AttributeMandatoryFormatDescriptionExample
GroupCountO-MInteger [0-3]Total number of colli in the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments
4
GroupSequenceO-MInteger [0-3]Sequence number of the collo within the complete shipment (e.g. collo 2 of 4)
Mandatory for multicollo shipments
2
GroupTypeO-MInteger [2]Group sort that determines the type of group that is indicated. This is a code. Possible values: 01 = Collection request 03 = Multiple parcels in one shipment (multicolli) 04 = Single parcel in one shipment03
MainBarcodeO-MString [11-15]Main barcode for the shipment (in case of multicolli shipments)
Mandatory for multicollo shipments
3SABCD6659149

ProductOption type

AttributeMandatoryFormatDescriptionExample
CharacteristicO-MInteger [3]The characteristic of the ProductOption. Mandatory for some products, please see the Products page118
OptionO-MInteger [3]The product option code for this ProductOption.
Mandatory for some products, please see the Products page
006

Response Labelling API

ResponseShipment type

Attribute  DescriptionExample
Barcode  Barcode of the shipment3SABCD6659149
CodingText     

CodingText used for mailbox parcels. If you are using GenerateLabelWithoutConfirm, please use this value in the Confirming request when confirming the shipment.

#2426A3A#03#0306#
DownPartnerBarcode  Barcode downstream network partner. This value will be generated for Combilabel shipmentsEA123456785NL
DownPartnerID  Identification downstream network partner. This value will be generated for Combilabel shipments.EURODIS
Labels  The list with the generated labels.  
ProductCodeDelivery  Product code of the shipment. This value can be changed by the label generation process.3085
Warnings  List of warnings 

Label type

Attribute  DescriptionExample
Content  Base64 encoded binary label
See Guidelines
 
Contenttype  

Content type of the label, e.g. zebra of pdf. See Guidelines

Note: It is not recommended to send .PDF files/labels directly to a Zebra printer. See Guidelines

PDF
Labeltype  Type of the label
See Guidelines
Label

Warning type

Attribute  DescriptionExample
Code  Warning code1003
Description  Warning description

Validation failed for shipment