Provider guides
PostNL: configuration and operations
Create PostNL barcodes and shipping labels, retrieve tracking and request optional delivery quotes.
On this page
Provider workflow
Create PostNL barcodes and shipping labels, retrieve tracking and request optional delivery quotes. This is the carrier adapter for the Core Physical capability, not a replacement for shipping zones, merchant rates or a PostNL account. Label files are stored on the local application disk.
Requirements
Agovena Core ^0.0.1. Core Physical commerce is available automatically; install this Extension only for PostNL integration.
This extension is not marked production-ready. Validate its supported workflow in your own test environment before accepting customer orders.
Set up the package
Configure Core Physical commerce, then enable PostNL. Configure api_key, customer_code and customer_number. collection_location is optional, sandbox defaults to true and default_product_code defaults to 3085. Add accurate shipping addresses and product weights. Confirm that your PostNL contract supports the selected service and destination before offering it.
Provider-specific boundaries
The API client selects api-sandbox.postnl.nl or api.postnl.nl from sandbox and sends the apikey header. It calls barcode, shipment, status and checkout endpoints. Provider HTTP 401 or 403 is treated as a configuration problem, 400 as an invalid address and 422 as an unsupported destination. These are different from an unreachable provider.
Test one complete Dutch address with a correctly split street and house number, then test an unsupported destination. Verify the barcode, saved label and tracking on the same shipment. Check actual provider quote amounts before relying on live quotes: returned options without a price can resolve to zero. Keep a deliberate merchant-rate strategy for unavailable quotes. After a timeout, inspect the known barcode or provider shipment before requesting another label. Test credentials and labels are not a production shipping agreement. 2
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" |
These are the declared manifest fields. A field marked optional may still be required by an API operation, as described above. Store secret values only in protected settings, never in product descriptions, URLs or shared examples. 1
Operation and failure handling
Incomplete addresses or quote API failures return no live quotes. Label creation validates the street and house number; service code 3085 is rejected for destinations outside the Netherlands. Existing order-to-barcode mappings are reused. Invalid or missing label data produces an error rather than an empty PDF. Cancellation through this adapter is unsupported. Resolve label cancellation through the carrier process instead of assuming local order cancellation retracts it.