Documentation
Method: POST
/label | Generate shipping labels |
Query parameter:
With the Confirm boolean in the request, you can determine if you want to confirm the shipment in the same call or not. If the Boolean variable is true the shipment will be preannounced. If this is set to false, then an additional Confirming API request needs to be made.
| Interface version | 2_2* |
| Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v2_2/label |
| Sandbox wsdl | https://api-sandbox.postnl.nl/shipment/v2_2/label/soap.wsdl |
| Sandbox swagger | https://api-sandbox.postnl.nl/shipment/v2_2/label/swagger.json |
| Production endpoint | https://api.postnl.nl/shipment/v2_2/label |
| Production wsdl | https://api.postnl.nl/shipment/v2_2/label/soap.wsdl |
| Production swagger | https://api.postnl.nl/shipment/v2_2/label/date/swagger.json |
REST:
API
| Version | Release Date | Status | Release Notes | Schema Changes |
Labelling | 2_1 | Jun 01, 2017 | Supported | IN COMPARISON TO THE 2_0 SOAP VERSION,
- DeliveryTimestampStart
NOTE: THIS PRODUCT NO LONGER EXIST. | N/A |
2_2 | Jan 25, 2019 | Current version | The following fields have been added to the interface for shipments to the USA: -Shipment.Customs.TrustedShipperID
-Shipment.CodingText (response)
| Yes |
| Version | Release Date | Status | Release Notes | Schema Changes | |
| 1_3 | Dec 27, 2012 | Not supported | |||
| 1_4 | Nov 8, 2013 | Not supported | The following fields have been added to the interface:
Shipment/Content Shipment/CostCenter Shipment/CustomerOrderNumber Shipment/Remark Shipment/ReturnReference Shipment/ReturnBarcode Amount/BIC Amount/IBAN The following fields have been removed from the interface: Amount/AccountNr To comply with SEPA regulation, the bank account details must be entered in IBAN format. The COD card has been changed to print the IBAN bank account number. | Yes | |
| 1_5 | Feb 27, 2014 | Not supported | Different namespace Note: due to changes in the backend the Label in the box (return label) functionality is only available from version 1_6 or later.
| Yes | |
| 1_6 | Aug 14, 2014 | Supported | Different namespace | Yes | |
| 1_7 | Nov 14, 2014 | Supported | The following field has been added to the interface:
Shipment.DownPartnerLocation | Yes | |
| 1_8 | Jan 12, 2015 | Not supported | The following fields have been added to the interface:
- Shipment.IDNumber - Shipment.IDType - Shipment.IDExpiration - Shipment.ReceiverDateOfBirth The field StreetHouseNrExt is now usable for locations in NL, BE and DE. | Yes | |
| 1_9 | Apr 24, 2015 | Not supported | The request now includes a field for adding a signature to the labels generated by the service. This field is optional, so no change is required to use the new version of the service.
Shipment validation errors now include an error code in addition to the error message. | Yes | |
| 2_0 | Aug 14, 2015 | Supported | Multiple shipments can now be sent in one request to the labelling service. 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.
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 new MergedLabels response field. If you want to send only one shipment, you have to specify the Shipments element containing one Shipment. | Yes | |
| 2_1 | July 15, 2017 | Supported | PostNL has implemented a commercial route to China. In order to do this, the following fields have been added to the interface: - Shipment.Customs.Content.Content.EAN
- DeliveryTimestampStart (Delivery on Demand label) - DeliveryTimestampEnd (Delivery on Demand label) | Yes | |
| 2_2 | Jan 25, 2019 | Current version | The following fields have been added to the interface for shipments to the USA: -Shipment.Customs.TrustedShipperID -Shipment.Customs.ImporterReferenceCode -Shipment.Customs.TransactionCode -Shipment.Customs.TransactionDescription -Shipment.CodingText (response) A Codingtext have been added to the labels for mailbox parcels (brievenbuspakjes). | Yes |
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.
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.
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.
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.
| 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.
| 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.
| Attribute | Mandatory | Format | Description | Example |
| Address | O-M | Address type | See 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. | |
| CollectionLocation | M | String | Code of delivery location at PostNL Pakketten | 123456 |
| ContactPerson | O | String | Name of customer contact person | Janssen |
| CustomerCode | M | String [1-4] | Customer code as known at PostNL Pakketten | ABCD |
| CustomerNumber | M | Integer [1-8] | Customer number as known at PostNL Pakketten | 1234567 |
| O | String [0-50] | E-mail address of customer | janssen@company.com | |
| Name | O | String [0-35] | Customer name | Janssen |
| Attribute | Mandatory | Format | Description | Example |
| O | Base64 | 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. |
| Attribute | Mandatory | Format | Description | Example |
| MessageID | M | String [1-12] | ID of the message | 1 |
| MessageTimeStamp | M | Datetime [19] | Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss | 29-06-2016 12:00:00 |
| Printertype | M | String [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 |
| Attribute | Mandatory | Format | Description | Example |
| Shipment | M | Shipment type | List of 1 or more ShipmentType elements of a shipment. At least one shipment type is required. Shipments for validation or
confirmation. |
| Attribute | Mandatory | Format | Description | Example |
| Addresses | M | Address type | List of 1 or more Address type elements
At least 1 address type is mandatory | |
| Amounts | 0-M | Amount type | List 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) | |
| Barcode | M | String [11-15] | Barcode of the shipment. This is a unique value | 3SABCD6659149 |
| CollectionTimeStampEnd | O | Datetime [19] | Ending date/time of the collection of the shipment | 04-06-2016 17:00:00 |
| CollectionTimeStampStart | O | Datetime [19] | Starting date/time of the collection of the shipment | 04-06-2016 19:00:00 |
| Contacts | O-M | Contact type | One or more ContactType elements belonging to a shipment
Mandatory in some cases. Please refer to the Guidelines | |
| Content | O-M | String [0-35] * | Content of the shipment
Mandatory for Extra@Home shipments | Media player |
| CostCenter | O | String [0-35] | Cost center of the shipment.
This value will appear on your invoice | SX-GT-66 |
| CustomerOrderNumber | O | String [0-35] | Order number of the customer. | 8689242390 |
| Customs | O-M | Customs type | The Customs type is mandatory for Parcels Non-EU shipments and not allowed for any other shipment types. | |
| DeliveryAddress | O-M | Integer [2] | Delivery address specification. This field is mandatory when AddressType on the Address is 09. | 02 |
| DeliveryTimestampEnd | O-M | Datetime [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 |
| DeliveryTimestampStart | O-M | Datetime [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 |
| DeliveryDate | O-M | datetime [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 |
| Dimension | M | Dimension type | Dimension of a shipment.
See the dimension type. | |
| DownPartnerBarcode | O-M | String [0-35] | Barcode of the downstream network partner of PostNL Pakketten.
| CD123456785NL |
| DownPartnerID | O-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 |
| DownPartnerLocation | O-M | String [0-10] | Identification of the location of the downstream network partner of PostNL Pakketten.
| BE0Q82 |
| Groups | O-M | Group type | List of 0 or more Group types with data, grouping multiple shipments together.
Mandatory for multicollo shipments. Please see Guidelines (Multiple shipments) for more information. | |
| IDExpiration | O-M | Date [10] | Expiration date of the ID document.
Mandatory for ID Check products | 05-06-2020 |
| IDNumber | O-M | String [0-20] | Document number of the ID document
Mandatory for ID Check products | 4261103214 |
| IDType | O-M | Integer [2] | Type of the ID document.
Mandatory for ID Check products. See Products for possible values | 03 |
| ProductCodeCollect | O | Integer [4] | Second product code of a shipment | 3153 |
| ProductCodeDelivery | M | Integer [4] | Product code of the shipment | 3085 |
| ProductOptions | O-M | ProductOption type | Product options for the shipment, mandatory for certain products, see the Products page of this webservice | |
| ReceiverDateOfBirth | O-M | Date [10] | Date of birth
Mandatory for Age check products | 10-12-1980 |
| Reference | O-M | String [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 |
| ReferenceCollect | O | String [0-35] | Additional reference of the collect order of the shipment. | 6659150 |
| Remark | O | String [0-35] | Remark of the shipment. Displayed on label, not used for data under GDPR. | Fragile |
| ReturnBarcode | O-M | String [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 |
| ReturnReference | O | String [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.
| Attribute | Mandatory | Format | Description | Example |
| AddressType | M | Integer [2] | Type of the address. This is a code. You can find the possible values at Guidelines | 02 |
| Area | O | String [0-35] | Area of the address | Beukenhorst |
| Buildingname | O | String [0-35] | Building name of the address | AA |
| City | M | String [0-35] * | City of the address | Hoofddorp |
| CompanyName | O-M | String [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 |
| Countrycode | M | String [2] | The ISO2 country codes | NL |
| Department | O | String [0-35] | Send to specific department of a company. | IT |
| Doorcode | O | String [0-35] | Door code of address | 123 |
| FirstName | O | String [0-35] * | Remark: please add FirstName and Name (lastname) of the receiver to improve the parcel tracking experience of your customer. | Peter |
| Floor | O | String [0-35] | Send to specific floor of a company. | 4 |
| HouseNr | O-M | String [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 |
| HouseNrExt | O | NL= String [0-6]
Outside of NL= String [0-35] | House number extension | A |
| Name | O-M | String [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 |
| Region | O | String [0-35] | Region | Noord-Holland |
| Remark | O | String [0-35] | Remark of the shipment. Displayed on label, not used for data under GDPR. | Fragile |
| Street | O-M | String [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 |
| StreetHouseNrExt | O-M | String [0-95] | Combination of Street, HouseNr and HouseNrExt. Please see Guidelines for the explanation | Siriusdreef 42 A |
| Zipcode | O-M | String [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.
| Attribute | Mandatory | Format | Description | Example | ||
| AccountName | O | String [0-35] | Name of bank account owner | C. de Ruiter | ||
| AmountType | M | Integer [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 | ||
| BIC | O-M | String [8-11] | BIC number, optional for COD shipments (mandatory for bank account number other than originating in The Netherlands) | RABONL2UXXX | ||
| Currency | O | String [3] | Currency code according ISO 4217. E.g. EUR | EUR | ||
| IBAN | O- M | String [15-31] | IBAN bank account number, mandatory for COD shipments. Dutch IBAN numbers are 18 characters | NL00RABO0123456789 | ||
| Reference | O | String [0-35] | Personal payment reference | 1234-5678 | ||
| TransactionNumber | O | String [0-35] | Transaction number | 1234 | ||
| Value | O-M | Decimal [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 |
| Attribute | Mandatory | Format | Description | Example |
| ContactType | M | Integer [2] | Type of the contact. This is a code. You can find the possible values at Guidelines | 01 |
| O-M | String [0-50] | Email address of the contact. Mandatory in some cases. Please see Guidelines | receiver@gmail.com | |
| SMSNr | O-M | String [10-17] | Mobile phone number of the contact. Mandatory in some cases. | 0612345678 |
| TelNr | O-M | String [10-17] | Phone number of the contact. | 0612345678 |
| Attribute | Mandatory | Format | Description | Example |
| Certificate | O-M | Boolean [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 |
| CertificateNr | O-M | String [0-35] | Mandatory when Certificate is true. | NR112233 |
| Content | M | Content type | This section is mandatory (minimum once, maximum 5) | |
| Currency | M | String [3] | Currency code, only EUR, GBD, USD and CNY are allowed. | EUR |
| HandleAsNonDeliverable | M | Boolean [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 |
| Invoice | O-M | Boolean [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 |
| InvoiceNr | O-M | String [0-35] | Mandatory when Invoice is true. | 22334455 |
| License | O-M | Boolean [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 |
| LicenseNr | O-M | String [0-35] | Mandatory when License is true | 11223344 |
| ShipmentType | M | String [1-35] | Type of shipment, possible values: Gift, Documents, Commercial Goods, Commercial Sample, Returned Goods | Commercial Goods |
| TrustedShipperID | O | String [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 |
| ImporterReferenceCode | O | String [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 |
| TransactionCode | O-M | String [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.
| 11 |
| TransactionDescription | O-M | String [0-50] | Transaction description
| Sale of goods |
| Attribute | Mandatory | Format | Description | Example |
| Description | M | String [1-35] | Clear description of the content of the item in English (description of goods) | Powdered milk |
| Quantity | M | Integer [1-4] | Fill in the total of the item(s) | 2 |
| Weight | M | Integer [1-20] | Fill in the weight of the item(s) in gram (gr) | 2600 |
| Value | M | Decimal [1-9] | Fill in the value of the item(s) | 20.00 |
| HSTariffNr | M | String [6] | Specify every item with the standard HS commodity code (HS-code), more information | 100878 |
| CountryOfOrigin | M | String [2] | Fill in the code of the country where the item was produced (ISO-code), more information | NL |
| Attribute | Mandatory | Format | Description | Example |
| Weight | M | Integer [0-20] | Weight of the shipment in grams
Approximate weight suffices | 4300 |
| Length | O | Integer [0-20] | The longest side of the shipment in millimeters (mm). | 700 |
| Width | O | Integer [0-20] | The second longest side of the shipment in millimeters (mm). | 500 |
| Height | O | Integer [0-20] | The shortest side of the shipment in millimeters (mm). | 300 |
| Volume | O-M | Integer [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.