Overview
PostNL is the Netherlands' primary postal and parcel carrier, handling the majority of domestic parcel deliveries and a significant share of international shipping from the Netherlands. For high-volume Dutch e-commerce operations, logistics providers, and fulfilment companies that have negotiated direct contracts with PostNL, the PostNL API provides direct access to PostNL's shipping infrastructure — label generation, track and trace, delivery options, pickup point locations, and timeframe calculations — without the intermediary layer that platforms like MyParcel or SendCloud add.
Direct PostNL API integration is the appropriate choice for operations that have outgrown the intermediary platform model — the high-volume shipper with a direct PostNL contract that gets favourable rates, the logistics provider that manages PostNL shipping on behalf of multiple clients, the fulfilment operation that needs deep integration with PostNL's systems beyond what intermediary APIs expose, or the developer building a shipping platform that needs direct carrier connectivity.
The PostNL API covers the full range of PostNL's shipping products. Domestic parcel delivery — the standard PostNL parcel service with the full range of delivery options (signature, only recipient, evening delivery, Sunday delivery, pickup point). International shipping — PostNL's international parcel and packet services for destinations in Europe and worldwide. Letterbox and packet products for smaller items. The business mail products for document and correspondence sending. And the specialised products — evening delivery, Sunday delivery, age check, ID check — that serve specific delivery requirement use cases.
We build PostNL API integrations for Dutch high-volume shippers, logistics providers, fulfilment operators, and e-commerce platforms that have direct PostNL contracts and need to connect their operational systems directly to PostNL's shipping API.
What PostNL Integration Covers
PostNL API authentication. The PostNL API uses API key authentication for the current REST API generation.
API key: the PostNL API key issued as part of the PostNL developer account and contract setup. The apikey header included in every PostNL API request — the single header that authenticates the request. Separate API keys for the sandbox environment (for development and testing) and the production environment. The sandbox environment at https://api-sandbox.postnl.nl/ and the production environment at https://api.postnl.nl/.
Customer code and number: in addition to the API key, PostNL API requests for label generation require the customer code (CustomerCode) and customer number (CustomerNumber) from the PostNL contract — the identifiers that associate generated labels with the correct PostNL account for billing and processing.
Generating shipping labels. The primary PostNL API operation — generating barcode-embedded shipping labels for parcels.
Confirming shipments: the POST /v1/shipment endpoint (Confirming API) for generating PostNL shipping labels. The request body with the Customer object (customer code, customer number, collection location code), the Message object (message ID, printer type, label format), and the Shipments array of shipment objects.
Shipment object: the Addresses array with the receiver address (AddressType: "01") and the sender address (AddressType: "02"). The Contacts array with the recipient contact information. The Dimension object with the weight in grams. The ProductCodeDelivery for the PostNL product code that determines the shipping product and available options.
Product codes: PostNL product codes that identify the specific shipping product — 3085 for standard domestic parcel, 3087 for standard parcel with signature, 3089 for standard parcel with only-recipient delivery, 3096 for evening delivery, 3385 for letterbox parcel, 4945 for PostNL International, and the other product codes for each PostNL shipping product. The product code selection that determines which delivery options are included and which barcode series is used.
Label response: the label generation response with the ResponseShipments array containing the barcode (track and trace code) and the Labels array with the base64-encoded label image data. The label image in PDF or ZPL format decoded from base64 and sent to the label printer.
Barcode generation: the GET /v1/barcode endpoint for pre-generating barcodes before label creation — the two-step approach where barcodes are generated first and then used in the shipment confirmation. The barcode series that matches the PostNL product and customer configuration.
Delivery options. Querying available PostNL delivery options for specific addresses and timeframes.
Delivery date: the GET /v1/deliverydate/delivery endpoint for calculating the earliest possible delivery date for a parcel — given the shipping date and cutoff time, when can PostNL deliver to the recipient? The delivery date calculation that e-commerce checkouts use to display accurate delivery date estimates to customers.
Shipping date: the GET /v1/deliverydate/shipping endpoint for calculating the latest possible shipping date to achieve a specified delivery date — the reverse calculation for operations that need to determine the shipping deadline for a promised delivery date.
Timeframes: the GET /v1/timeframe/calculate/timeframes endpoint for retrieving available delivery timeframes for a specific address — the morning, afternoon, and evening delivery window options that PostNL offers for specific postal code and date combinations. The timeframe data for e-commerce checkout delivery preference selection.
Pickup points and locations. Querying PostNL pickup point locations for customers who prefer parcel locker or PostNL service point collection.
Nearest locations: the GET /v1/locations/nearest endpoint for retrieving the nearest PostNL pickup points to a given address or coordinates — the list of PostNL retail locations, parcel lockers (PostNL-automaat), and partner pickup points within a defined radius. The pickup point data with location name, address, opening hours, and the location code used to designate a pickup point delivery.
Location details: the GET /v1/locations/lookup endpoint for retrieving details of a specific PostNL location by its location code.
Pickup point delivery: the shipment with a pickup point delivery address — the AddressType: "09" pickup point address type with the location code that designates the PostNL location where the parcel should be delivered. The customer who selects pickup point delivery at checkout receives the parcel at their chosen PostNL location rather than at their home address.
Track and trace. Retrieving shipment status and tracking information.
Shipment status: the GET /v1/status/barcode/{barcode} endpoint for retrieving the current status of a shipment by barcode. The status response with the current phase, the status description, and the event history — the delivery events that show where the parcel is in the PostNL network.
Status phases: PostNL shipment status phases — phase 1 (collection from sender), phase 2 (sorting at PostNL), phase 3 (out for delivery), phase 4 (delivered or delivery attempt). The phase and status code combination that determines the current state of the shipment.
Batch status: the POST /v1/status/barcode endpoint for querying the status of multiple barcodes in a single request — the bulk status check for monitoring many outstanding shipments.
Sending notification emails. PostNL's ability to send delivery notification emails to recipients on behalf of the sender.
Notification configuration: the email notification option in the shipment object that instructs PostNL to send delivery notification emails to the recipient — the track and trace email that keeps recipients informed of their parcel's progress without requiring the e-commerce platform to implement its own tracking notification system.
International shipping. PostNL's international parcel and packet products for cross-border shipments.
International product codes: the PostNL product codes for international shipping — 4945 for PostNL International packets, 4947 for international packets with track and trace, the business-to-business international parcel products. The product code selection based on destination country, weight, dimensions, and required service level.
Customs documentation: the Customs object in the international shipment request — the customs declaration required for non-EU shipments. The customs object with the ShipmentType (gift, documents, commercial goods), the InvoiceNr, the TrustedShipperID for operators with trusted shipper status, and the Content array of customs line items with description, quantity, weight, value, HS code, and country of origin.
International delivery options: the available services for international destinations — standard delivery, tracked delivery, and the delivery confirmation options that vary by destination country and product.
Address validation. Validating Dutch delivery addresses using PostNL's address database.
Address check: the PostNL address database contains the authoritative Dutch address data — postal code and house number combinations that map to validated street names and cities. The address validation that catches incorrect recipient addresses before labels are generated, reducing failed delivery attempts.
Label formats and printing. PostNL label output in the formats that label printers require.
GraphicFile format: the Printertype parameter in the label request — GraphicFile|PDF for PDF output, GraphicFile|PDF|mergedlabel for merged PDF with multiple labels, ZEBRA|Starline and ZEBRA|Starline|landscape for Zebra thermal printer ZPL format. The format selection that matches the label printer used at the packing station.
Label dimensions: the PostNL A6 label format (100x148mm) for standard label printers and the A4 format with multiple labels per page for desktop printer environments.
Label caching: the base64-encoded label data from the API response stored in the database alongside the barcode for reprinting without re-querying the PostNL API — the reprint capability for damaged or misprinted labels.
PostNL Checkout API. The checkout integration that surfaces PostNL delivery options at e-commerce checkout.
Delivery options at checkout: the combination of timeframe calculation, pickup point lookup, and delivery date calculation that presents PostNL delivery preferences to customers during checkout — home delivery with timeframe selection, pickup point selection, and evening or Sunday delivery options. The checkout API that e-commerce platforms use to surface PostNL's full delivery option range.
Integration Patterns
High-volume label generation. The warehouse management system or order management system that generates PostNL labels in bulk at packing stations — the label generation workflow that processes many shipments simultaneously using PostNL's batch label capabilities. The barcode pre-generation approach that generates barcodes before picking and packing, allowing the barcode to be printed on the pick list and scanned at the packing station for label retrieval without regenerating.
E-commerce checkout integration. The PostNL checkout integration that presents delivery options to customers during the checkout process — timeframes, pickup points, and delivery date estimates displayed in real time as the customer enters their delivery address. The checkout integration that captures the customer's delivery preference and uses it in the subsequent label generation.
Shipment monitoring. The status monitoring system that tracks outstanding PostNL shipments through the delivery lifecycle — querying the track and trace API for all active shipments, detecting exceptions (failed delivery attempts, return to sender), and triggering customer notifications or operational interventions when exceptions occur.
Multi-client logistics platform. The logistics provider or fulfilment platform that manages PostNL shipping on behalf of multiple client accounts — using the PostNL API with client-specific customer codes to generate labels billed to each client's PostNL account. The platform that provides PostNL shipping capabilities to clients without requiring each client to have their own API integration.
Technologies Used
- C# / ASP.NET Core — primary PostNL integration implementation using .NET HTTP client with JSON serialisation for the PostNL REST API
- Rust / Axum — high-performance PostNL label generation for very high-volume shipping operations where throughput is a primary constraint
- TypeScript / Node.js — PostNL integration for Node.js-based e-commerce and order management platforms
- Python — PostNL API scripting and data processing for fulfilment operations
- REST / HTTP — PostNL API communication
- SQL (PostgreSQL / MySQL) — shipment records, barcode-to-order mapping, label storage, tracking history
- Redis — barcode caching, label caching for reprint, status tracking, job coordination
- ZPL / PDF — label format output for thermal label printers and PDF-based printing
- Hangfire / scheduled jobs — batch shipment status polling, exception detection, daily shipment reporting
- Docker — containerised integration service deployment
- GitHub Actions — CI/CD pipeline for integration service deployment
Direct PostNL vs Intermediary Platform
The choice between direct PostNL API integration and an intermediary platform like MyParcel or SendCloud depends primarily on volume and contract status.
Intermediary platforms (MyParcel, SendCloud) are appropriate for businesses without direct PostNL contracts, for lower-volume shippers who benefit from the intermediary's consolidated rates, and for businesses that need multi-carrier flexibility without separate integrations for each carrier. The intermediary handles the PostNL API complexity and billing.
Direct PostNL integration is appropriate when the business has negotiated a direct PostNL contract with volume-based rates that are better than intermediary rates, when the operation needs access to PostNL products or API capabilities that the intermediary does not expose, when the operation needs to provide PostNL shipping as a platform to its own clients (using their own PostNL customer codes), or when the intermediary's API limitations constrain the integration requirements.
The integration architecture built for direct PostNL access — the label generation service, the track and trace monitoring, the checkout delivery option service — is structurally similar to the MyParcel or SendCloud integration but communicates directly with PostNL's API using the contract credentials rather than the intermediary's credentials.
PostNL Connected to Your Shipping Operations
PostNL API integrations built for high-volume production use — correct customer code and product code configuration, batch label generation for packing station throughput, ZPL and PDF label format support for thermal and desktop printers, track and trace monitoring with exception detection, and the operational reliability that daily fulfilment operations depend on.