Provider guides
PostNL: configuration and operations
Create pre-announced PostNL shipments with barcodes and labels, follow tracking and use priced PostNL delivery options when available.
On this page
Status and workflow
The PostNL extension is a carrier for the shipping features in Agovena Core. It creates a pre-announced PostNL shipment with barcode and label, reads tracking and can add priced PostNL delivery options to checkout. It is an Extension, not a Module: orders, products and addresses keep their generic Core fields, and PostNL barcodes, labels and product codes stay inside this extension.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the PostNL REST APIs for barcodes, labels, shipment status and checkout and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own PostNL account remains an operator responsibility: create one shipment, download its label and follow its tracking with your own PostNL contract before you ship customer orders. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. Physical commerce and shipping are part of Core, so no additional Module is required. - A PostNL API contract with an API key, customer code and customer number.
- Complete shipping addresses. The extension parses the street and house number from the first address line.
Set up the package
- Open Admin > Extensions and enable PostNL.
- Save the API key, customer code and customer number. The API key is encrypted and never redisplayed.
- Optionally set
collection_location. Keepsandboxenabled for tests (https://api-sandbox.postnl.nl) and switch it off with live credentials (https://api.postnl.nl). - Keep your Core shipping methods and rates configured. Checkout keeps using them for prices.
- Fulfillment uses the selected product code or
default_product_code, which defaults to3085(Standard NL). Confirm that your contract covers the products and destinations you offer.
Supported operations
| Operation | Endpoint |
|---|---|
| Health check and barcode | GET /shipment/v1_1/barcode |
| Pre-announced shipment with label | POST /shipment/v2_2/label?confirm=true |
| Tracking | GET /shipment/v2/status/barcode/{barcode} |
| Delivery options | POST /shipment/v1/checkout |
Every call uses the apikey header. Tracking reads CurrentStatus.Shipment.Status.PhaseCode: phases 2 and 3 become shipped, phase 4 becomes delivered and every other phase keeps the shipment in processing.
The PostNL Checkout API returns delivery options, not tariffs. Options without a positive price are skipped, so an unpriced option never becomes a free shipping quote and your Core rates stay in charge.
Domestic parcels and EU destinations without customs data are supported. Label PDFs are stored on the private local disk and can only be downloaded from Admin fulfillment. Customers see tracking, not the label file.
Not supported
- Cancelling a pre-announced parcel. The PostNL API does not support it and the request fails with a clear error.
- Shipments that need customs declarations. PostNL rejects them and Agovena shows a safe validation error.
- Reprinting a failed label from Agovena. Reprint it from Mijn PostNL for the stored barcode.
- Shipping prices from PostNL. Checkout prices come from your Core shipping rates unless PostNL returns a priced option.
Failure handling and ownership
- PostNL documents no idempotency header, so the extension enforces one parcel per order. Shipment creation holds a short lock per order and a concurrent attempt fails before any provider call.
- The barcode is stored as soon as PostNL confirms the shipment and before the label is decoded. A label failure therefore never leads to a second pre-announced parcel on retry, and a repeated request for an order with a PostNL barcode returns the existing mapping.
- A shipment whose label could not be stored keeps status
label_failedwithout a label file. - Without the
postnl_shipmentstable the extension refuses to call PostNL. - HTTP 401 and 403 are reported as a configuration problem, 400 as an invalid address and 422 as an unsupported destination.
- Redirects are never followed and automated tests never call the live API.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
api_key |
string |
Yes | Yes | Empty |
customer_code |
string |
Yes | No | Empty |
customer_number |
string |
Yes | No | Empty |
collection_location |
string |
No | No | Empty |
sandbox |
boolean |
No | No | true |
default_product_code |
string |
No | No | "3085" |
Keep sandbox enabled until a test shipment succeeds. default_product_code is used when an order has no selected PostNL product. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.