VibeFox PostNL for Adobe Commerce — Hilfe

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules. The pickup point list works on the standard Magento checkout (Luma or a theme based on it).

PHP: 8.1 to 8.4, with the cURL, JSON, SimpleXML and mbstring extensions.

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 does not need a key.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-postnl-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/PostnlShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PostnlShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox PostNL. Paste your VibeFox license key into License key in the license block, the first row of the group, 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). Set Enable PostNL to Yes and click Save Config.

The module adds the PostNL shipping method to Magento with two options. With the default names customers see them as PostNL - PostNL pickup point and PostNL - PostNL (carrier title and the name of the option). Both options are switched on inside the module, but the method is off after installation (Enable PostNL = No), and it is offered only to the Netherlands and Belgium until you change Ship to Specific Countries. The module also creates the table vfd_ptnl_point for the pickup points of carts and orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox PostNL, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Carrier title, Home delivery name and Pickup point name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts and weights accept "9.99" and "9,99", also with a thousands separator.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Carrier title, Home delivery name or Pickup point name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a Minimum weight (kg) greater than the Maximum weight (kg). An invalid or negative number in an amount or weight field is cleared with a warning, and the rest of the page is saved.

While Enable PostNL is Yes, warnings after saving remind you of missing settings: no API key for pickup points, no valid ship-from postcode for pickup points, the sandbox turned on, no country prices and no fallback cost, and a store weight unit the module does not know. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable PostNL: the master switch for pickup points and home delivery. Default: No.

Carrier title: the carrier name shown in the cart and at checkout, before the name of the option. Default: PostNL. Required, at most 64 characters.

Enable home delivery: turns the home delivery option on or off. No point is chosen. Home delivery needs a price, but no API key. Default: Yes.

Home delivery name: shown after the carrier title, as "Carrier title - Home delivery name". Default: PostNL. Required, at most 64 characters.

Enable pickup points: turns the pickup point option on or off. The customer must choose a PostNL point at checkout. It is offered only for addresses in the Netherlands and Belgium, only with an API key and only when PostNL returns points for the address. Default: Yes.

Pickup point name: shown after the carrier title, as "Carrier title - Pickup point name". Default: PostNL pickup point. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

PostNL Checkout API (not needed for home delivery)

API key: your PostNL API key from Mijn PostNL (My account > API beheren). It is sent only from your server, in the "apikey" header, and never shown to customers or written to the log. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config. The pickup point option is then no longer offered.

Sandbox: uses the PostNL sandbox (api-sandbox.postnl.nl). A separate PostNL sandbox key is required. Customers then see test pickup points. Default: No; keep it off on a live store.

Ship from (country): the sender country for pickup point requests, 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 1234 in Belgium. Leave it empty to use the origin postcode of Stores > Configuration > Sales > Shipping Settings > Origin, but only when its country matches Ship from (country). The city and street of the sender also come from that origin address when the country matches. An invalid postcode is saved empty with a warning. Without a sender postcode, no pickup points can be loaded.

Last API error: the last failed PostNL request with its date (UTC), or No recorded PostNL API error. It is read from the existing cache. Opening or saving the settings does not call PostNL. 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.

Rates (in the base currency of your store, tax excluded)

Prices apply to both options. PostNL has no public rate API, so the module does not request live rates. Magento shows the price in the customer's currency. If your store charges tax on shipping, set it in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Country prices: one row per destination country. Click Add country to add a row and Delete 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 positive weight class price overrides Price; leave it empty (or 0) to use Price. A Price of 0 means free shipping. Empty rows are dropped when you save. If a country appears twice, the first row is kept. Invalid cells are cleared with a warning, and the valid prices are saved.

Calculation type: Per order (default) charges the price once. Per item multiplies the price for the weight class of the whole cart by the number of items that need shipping.

Fallback cost: used when the table has neither the country nor a * row. Leave it empty to hide the method there. 0 means free delivery.

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

Availability

Minimum weight (kg): hide the method when the cart weighs less. Empty or 0 disables the minimum.

Maximum weight (kg): hide the method for heavier carts. Default: 30 (PostNL parcels go up to 30 kg in the Benelux). An empty field is saved as 30. An explicit 0 disables the limit.

Minimum subtotal: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. Leave it empty to always show it.

Ship to Applicable Countries: All Allowed Countries offers PostNL for every country your store allows, Specific Countries (default) only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Initially the Netherlands and Belgium. Home delivery can serve another allowed country that has a price; the pickup point option stays limited to the Netherlands and Belgium.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). The weight classes use the actual cart weight (the sum of product weights). Magento products have no standard dimensions, so volumetric weight is not calculated.

Advanced

Debug log: writes debug messages to var/log/vfd_ptnl_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors are always logged, even when this is off. The API key and customer addresses are never logged. 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 Yes, uninstalling the module with its data deletes the PostNL settings, the log and the pickup points of carts that never became an order (see Uninstall). The license key, the cached point lists and the last API error are always removed. The pickup points of orders are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the PostNL prices. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks the countries, the cart weight and Minimum subtotal. Then it takes the price from the table for the country and weight class, or the fallback cost. If there is no price, the method is hidden. If the cart subtotal reaches Free shipping from, the price is 0. A Magento cart price rule with free shipping also makes the price 0; the weight limits, the countries and the pickup point conditions still apply.

The pickup point option is offered only for addresses in the Netherlands and Belgium and only with an API key. When the delivery address has a complete 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 home delivery. If PostNL cannot be reached or has no points for the address, the pickup point option is hidden and home delivery stays available. The API timeout is 12 seconds.

Point lists are cached for 6 hours per address, 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 in Last API error. The cache is kept separately for each store view.

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. The pickup point option is meant for the storefront checkout: an order with a pickup point cannot be created in the Admin, because the point is chosen by the customer.

Pickup points

When the customer selects the pickup point option, a PostNL pickup point list appears under it with the nearest points: company name, address and distance. Before a complete postcode is entered, the customer sees "Enter a complete Dutch postcode (for example 2595AK) to choose a pickup point." (for Belgium: "Enter a complete Belgian postcode to choose a pickup point."). The chosen point is saved to the cart right away and shown under the list. It belongs to the country and postcode of the delivery address: when the address changes, the customer chooses again.

The point is required. Without one, the customer cannot continue and sees "Please choose a PostNL pickup point." When the customer clicks Next, the server checks the point again against PostNL's list for the delivery address (also for orders placed through the REST API), and once more before the order is placed. If it is not on the list, the customer sees "This PostNL pickup point is not available for the delivery address." If PostNL has no points, the customer sees "No PostNL pickup points were found for this address. Please choose home delivery."; if PostNL cannot be reached, "PostNL pickup points are temporarily unavailable. Please try again or choose home delivery." The name and address saved with the order come from PostNL, not from the browser.

The point is fixed when the order is placed; a later change in the cart does not change the order. If the customer cancels the payment at a payment provider and Magento restores the cart, the customer can choose a pickup point again and place the order. The new order gets the new point, and the earlier order keeps its own.

Admin order page: on Sales > Orders > View, Information tab, a PostNL pickup point block shows the name and address, the reference (country and PostNL location code, for example NL-176227) and the Partner ID.

Customer account and guest orders: the order page in the customer account and the guest order page (Orders and Returns) show PostNL pickup point with the name, address and reference.

Order e-mails: the point name, address and reference are added to the shipping description of the order, so they appear in the order e-mails and on the order pages.

The blocks also work for older orders and when the module is switched off. Home delivery orders have no pickup point.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PostNL is the first row of the VibeFox PostNL group in Stores > Configuration > Sales > Delivery Methods, 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 store. Below them are the line Product: magento-shipping-postnl and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the PostNL method is not shown to customers at checkout, no shipping price is calculated and no pickup points are loaded. The Magento storefront does not know that you are logged in to the Admin, so the method is 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

PostNL does not appear at checkout: check that the license is active and Enable PostNL is Yes for the website of the store, and that Enable home delivery or Enable pickup points is on. Check Ship to Applicable Countries and Ship to Specific Countries (initially only the Netherlands and Belgium), that a price or a Fallback cost is set for the country, the weight limits and Minimum subtotal.

The pickup point option 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 after Save Config, the Last API error field and the Log field. Errors are always logged; turn on Debug log for details.

"PostNL pickup points are temporarily unavailable": PostNL could not be reached, rejected the API key or the ship-from postcode is missing. Last API error shows the last error. A sandbox key works only with Sandbox on, and a live key only with it off. Failed requests are retried after 10 minutes, or at once after you change the API key, the sandbox setting or the ship-from address.

Customers see test pickup points: set Sandbox to No.

Product weights look wrong: if a warning says that the store weight unit is not known, set Weight Unit to lbs or kgs in Stores > Configuration > General > General > Locale Options. Until then, product weights are read as kg.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key, the settings and the table vfd_ptnl_point stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PostnlShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PostnlShipping to remove the data, then bin/magento module:disable Vibefox_PostnlShipping, delete the folder app/code/Vibefox/PostnlShipping and run bin/magento setup:upgrade.

The license key, the license status, the cached pickup point lists and the last API error are always removed. If Remove data on uninstall is Yes, the PostNL settings, the log and the pickup points of carts that never became an order are removed too. If it is No, the settings are kept for a re-install. The module never deletes the pickup points of orders, so existing orders keep their shipping description and their saved pickup point.

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