VibeFox PostNL for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

PostNL API key (for pickup points only): pickup points are loaded from the PostNL Checkout API. PostNL business customers find the API key in Mijn PostNL under My account > API beheren. The PostNL sandbox needs a separate sandbox key. Home delivery methods do not need a key.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_postnl folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox PostNL, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Fill in the prices. For pickup points also enter the PostNL API key and the Ship from (postcode) (see Configuration).

6. Add VibeFox PostNL to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, for example Netherlands and Belgium. In the zone set the Title and Delivery to. Add the method a second time for the other delivery type.

Configuration

All settings except the title and the delivery type are on one page: WooCommerce > Settings > Shipping > VibeFox PostNL. They apply to every shipping zone. When you add the method to a zone, the zone window has two fields:

Title (zone): the name customers see for this zone method. Leave it empty to use the global Name.

Delivery to (zone): As in the global settings (default), PostNL pickup point (customer chooses a point) or Home address. Add the method twice to a zone to offer both.

Above the settings the page shows warnings: a missing API key or ship-from postcode for pickup points, the sandbox turned on, no price set, and the last failed PostNL request with its date and error.

General

Enable/Disable: turns PostNL delivery on or off in all zones at once.

Name: the shipping method name shown at checkout. A Title set in the zone overrides it. Default: PostNL.

Delivery to: the default delivery type for zone methods that use As in the global settings, and for the Ignore zones mode.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not.

PostNL API (pickup points) (not needed for home delivery)

API key: your PostNL API key from Mijn PostNL (My account > API beheren). It is sent to PostNL in the "apikey" header, stored in the WordPress database and never shown to customers or written to the log.

Sandbox: uses the PostNL sandbox (api-sandbox.postnl.nl) with a sandbox API key. Customers then see test pickup points. Keep it off on a live shop.

Ship from (country): the country where you hand your parcels to PostNL, Netherlands or Belgium. By default it is your store country. PostNL uses the sender address for the pickup date.

Ship from (postcode): the sender postcode, for example 1234AB in the Netherlands or 1000 in Belgium. Leave empty to use the store postcode from WooCommerce > Settings > General when the store is in the same country. An invalid postcode is refused with a message. When you change the API key, the sandbox setting or the ship-from address, the cached pickup point lists are cleared.

Prices (in the store currency)

PostNL has no public rate API, so the plugin does not request live rates and never converts prices.

Price per country: one row per destination country. Click + Add country to add a row and the cross to remove one. Choose * All other countries for a row that covers every country without its own row. Each row has a Price and optional weight classes by cart weight: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL above 5 kg. A weight class price overrides Price; leave it empty to use Price. A Price of 0 means free shipping. Both "6.95" and "6,95" are accepted. Empty rows and invalid country codes are removed when you save. If a country appears twice, the first row is kept. Invalid prices are ignored with a message.

Calculation: Per order charges the price once. Per item (price x quantity) multiplies it by the number of shippable items in the cart.

Price for other countries: used when the table has neither the country nor a * row. Leave it empty to hide the method there.

Conditions

Free shipping from: the cart subtotal from which delivery is free. It applies only where a price is found. Leave empty to never offer free shipping.

Minimum subtotal: show the method only when the cart subtotal is at least this amount. Leave empty to always show it.

Minimum weight (kg): hide the method when the cart weighs less. Product weights are converted from your store unit. Leave empty for no limit.

Maximum weight (kg): hide the method for heavier carts. Default: 30 (PostNL parcels go up to 30 kg in the Benelux). Leave empty for no limit.

Hide for shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

All amounts and weights accept a decimal comma, also with a thousands separator (1.234,50 or 1,234.50). An invalid number is ignored with a message.

Availability without shipping zones

Ignore zones: also offer PostNL to the countries below when no zone adds it. Zones that contain the method keep working as usual. This mode uses the global Name and Delivery to.

Countries: the destination countries for that mode. Leave empty to use every country the store ships to. This field is used only when Ignore zones is on.

Advanced

Debug log: writes debug messages to WooCommerce > Status > Logs (source "vfd-postnl"). API errors are always logged. No API key or customer data is written. Turn the log off when you are done.

Remove data on uninstall: when on, deleting the plugin removes the PostNL settings and zone methods. Deactivating the plugin never deletes settings. Pickup points saved in orders are always kept.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin checks the conditions: cart weight, minimum subtotal and shipping classes. Then it takes the price from the table for the country and weight class, or the price for other countries. If there is no price, the method is hidden. If the cart subtotal reaches Free shipping from, the price is 0.

A pickup point method is offered only for addresses in the Netherlands and Belgium and only with an API key. As soon as the customer has entered a valid postcode, the plugin asks the PostNL Checkout API for the nearest pickup points. It sends the customer's postcode, street, house number, city and country, and your ship-from address. Nothing is sent for home delivery methods. If PostNL cannot be reached or has no points for the address, the pickup point method is hidden and your other methods stay available. The API timeout is 12 seconds.

Point lists are cached for 6 hours per postcode, and "no points" answers for 1 hour. Failed requests are cached for 10 minutes, so an outage does not slow down every checkout refresh. The last error is shown on the settings screen.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin does not request live PostNL rates and does not create shipping labels, barcodes, track and trace, returns or pre-alerts. It has no delivery-day, evening or morning delivery options. Create the shipment in Mijn PostNL or another PostNL tool using the saved pickup point.

Pickup points

When the customer selects a pickup point method, a PostNL pickup point list appears under it with the three nearest points: company name, address and distance. Before a postcode is entered, the customer sees "Enter your postcode (for example 1234 AB) to see PostNL pickup points." (4 digits for Belgium). The choice is remembered when the checkout refreshes.

The point is required. Without one, checkout stops with "Please choose a PostNL pickup point." The server checks the point against PostNL's list for the shipping address. If it is not on the list, checkout stops with "The chosen PostNL pickup point is not available for this address. Please choose it again." The name and address saved with the order come from PostNL, not from the browser.

Admin order screen: PostNL pickup point with the name and address and the Location code, below the shipping address.

Thank-you page and My account order view: PostNL pickup point with the name and address.

Order e-mails: the point name and address in HTML and plain-text e-mails.

In the database the point is stored in the order meta _vfd_ptnl_servicepoint_id (PostNL location code), _vfd_ptnl_servicepoint_name (name and address) and _vfd_ptnl_servicepoint (partner ID, company, street, house number, postcode, city, country).

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox PostNL. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, PostNL is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

PostNL does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore zones is on and the country is allowed). Check that a price is set for the country, the weight limits, Minimum subtotal and Hide for shipping classes.

The pickup point method does not appear: it is shown only for Dutch and Belgian addresses, only with an API key, a ship-from postcode and a price, and only when PostNL returns points for the customer's postcode. Check the warnings on top of the settings screen and WooCommerce > Status > Logs, source "vfd-postnl". Errors are always logged; turn on Debug log for details.

"PostNL pickup points cannot be loaded right now": PostNL could not be reached, rejected the API key or the ship-from postcode is missing. The settings screen shows the last error. A sandbox key works only with Sandbox on, and a live key only with it off.

Customers see test pickup points: turn Sandbox off.

Filters for developers: vfd_ptnl_number_of_locations (default 3), vfd_ptnl_checkout_request (request body) and vfd_ptnl_api_url.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all settings and only clears the cached pickup point lists. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, together with the cached pickup point lists and the last API error. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines and the saved pickup point.

PostNL is a trademark of its respective owner. This plugin is not affiliated with or endorsed by PostNL.