VibeFox PostNL for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x, Classic or Hummingbird theme (or a theme based on them).

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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. The home delivery carrier does not need a key.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox PostNL in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

On install the module creates two carriers: PostNL pickup point with the delivery time text Delivery to a PostNL pickup point, and PostNL with PostNL delivery to the home address. Both are linked to the zones of the Netherlands and Belgium and to all customer groups. You can add zones and change customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox PostNL > Configure. Each section has its own Save button, which saves the whole page. In WooCommerce one method is added to a zone twice, once per delivery type. In PrestaShop each delivery type is a carrier of its own, with its own name, status and zones.

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, the last failed PostNL request with its date and error, a shop weight unit the module does not know, and a deleted carrier.

General

PostNL pickup point: turns the pickup point carrier on or off. The customer must choose a PostNL point at checkout. It is offered only for addresses in the Netherlands and Belgium and only with an API key. This is the same switch as the carrier status in Shipping > Carriers.

Pickup point carrier name: the name customers see at checkout. Default: PostNL pickup point. Required.

PostNL home address: turns the home delivery carrier on or off. No point is chosen. It works for every country with a price. Same switch as the carrier status.

Home delivery carrier name: the name customers see at checkout. Default: PostNL. Required.

Tax status: the tax rule of both carriers. A Taxable rule adds the shipping tax of that rule on top of the prices. None means the prices are final.

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 and never shown to customers or written to the log. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it.

Remove the saved API key: tick it and click Save to delete the saved key. The pickup point carrier is then no longer offered.

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. Default: Netherlands. 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 shop postcode from Shop Parameters > Contact > Stores when the shop is in the same country. An invalid postcode is saved empty with a warning. When you change the API key, the sandbox setting or the ship-from address, the cached pickup point lists and the last API error are cleared.

Prices (in the shop default currency, tax excluded)

Prices apply to both carriers. PostNL has no public rate API, so the module does not request live rates. For a customer who pays in another currency, PrestaShop converts the price with the currency rate of your shop.

Price per country: one row per destination country. Click + Add country to add a row and the trash icon 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. "6.95", "6,95" and amounts with a thousands separator such as "1.234,50" or "1,234.50" 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 warning.

Calculation: Per order charges the price once. Per item (price x quantity) multiplies it by the number of items that need shipping.

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

Conditions

Free shipping from: the cart subtotal (products that need shipping, tax excluded, after discounts) from which delivery is free. It applies only where a price is found. Leave empty to never offer free shipping.

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

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

Maximum weight (kg): hide the carriers for heavier carts. Default: 30 (PostNL parcels go up to 30 kg in the Benelux). 0 means no limit. If you leave it empty, 30 kg applies in the zones of the carriers and no limit applies only to the countries reached through Ignore zones. A minimum weight above the maximum weight is refused with an error, because the carriers would never be shown.

All amounts and weights accept a decimal comma, also with a thousands separator. An invalid or negative number is ignored with a warning, and the field is saved empty.

Availability without shipping zones

Normally the carriers are offered in the shipping zones they are linked to in Shipping > Carriers.

Ignore zones: also offer PostNL to the countries below where its zones do not contain them. The carriers are then linked to every active zone, also to zones you create later. When you switch it off again, the carriers get back the zones they had before.

Countries: the destination countries for that mode. Leave empty to allow every country. This field is used only when Ignore zones is on. In those countries both carriers can be offered; the pickup point carrier still only for the Netherlands and Belgium.

Advanced

Debug log: writes debug messages to logs/vfd_ptnl_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged. No API key or customer data is written. Turn the log off when you are done.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the module deletes the PostNL settings and carriers. When off, uninstalling only switches the carriers off. Pickup points saved on orders are always kept.

How it works at checkout

At the shipping step PrestaShop asks the module for the price of each PostNL carrier. Only physical products count: virtual products add no weight and are not included in the subtotal. The module checks the conditions: cart weight and minimum subtotal. 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 carrier is hidden. If the cart subtotal reaches Free shipping from, the price is 0.

The pickup point carrier is offered only for addresses in the Netherlands and Belgium and only with an API key. When the delivery address has a valid postcode, the module asks the PostNL Checkout API for the three nearest pickup points. It sends the customer's postcode, street, house number, city and country, and your ship-from address. Nothing is sent for the home delivery carrier. If PostNL cannot be reached or has no points for the address, the pickup point carrier is hidden and the home delivery carrier stays 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 module page.

If you edit a carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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 the pickup point carrier, a PostNL pickup point list appears under it with the three nearest points: company name, address and distance. The page never waits for PostNL: if the list is not cached yet, it is loaded as soon as the carrier is selected. Before a full postcode is entered, the customer sees "Enter your postcode (for example 1234 AB) to see PostNL pickup points." (4 digits for Belgium). The chosen point is saved to the cart and kept when the checkout refreshes.

The point is required. Without one, the customer cannot continue and sees "Please choose a PostNL pickup point." When the customer clicks Continue, the server checks the point against PostNL's list for the delivery address. If it is not on the list, the customer sees "The chosen PostNL pickup point is not available for this address. Please choose it again." If PostNL cannot be reached, the customer sees "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." A point chosen for another address is never used for the order. The name and address saved with the order come from PostNL, not from the browser.

Admin order page: a PostNL pickup point block with the name and address, the Location code and the Partner ID.

Order confirmation and order detail pages: PostNL pickup point with the name and address.

Order e-mails: the point name and address are added to the carrier name in the order confirmation e-mail. The shop's new order e-mail (Mail alerts module) also shows the location code.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PostNL is the first block on Modules > Module Manager > VibeFox PostNL > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-postnl and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the PostNL carriers are not shown to customers at checkout and no shipping price is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carriers are hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the module always removes the license key and license status. Reset of this module does not delete data, so the key and the status are kept.

Troubleshooting

PostNL does not appear at checkout: check that the license is active and the carrier switch is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or that Ignore zones is on and the country is allowed). Check that a price is set for the country, the weight limits and Minimum subtotal. Products can also be limited to certain carriers in the product page.

The pickup point carrier 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 module page and the Log field. 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 module page 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.

Product weights look wrong: if the module page warns that the shop weight unit is not known, set a standard unit (kg, g, lb or oz) in International > Localization under Local units. Until then, product weights are read as kg.

The page says a PostNL carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps your settings and the status of the carriers.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox PostNL and choose Uninstall. The license key and the license status are always removed. The cached pickup point lists and the last API error are always removed. If Remove data on uninstall is on, the carriers are deleted (orders keep their history) and the settings and log are removed. If it is off, the carriers are only switched off and all settings are kept. Installing the module again gives the carriers back the status they had. Existing orders keep their shipping lines and the saved pickup point.

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