VibeFox PostNL for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_postnl-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_postnl.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_postnl-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox PostNL and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

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

5. Turn on PostNL pickup point and/or PostNL home address and fill in the prices. For pickup points also enter the PostNL API key and the Ship from (postcode) (see Configuration). Click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_postnl.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox PostNL, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install both options are off until you turn one on and save. If you install the extension again after an uninstall, the PostNL settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox PostNL > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Only admin users with the modify permission for this extension can save the settings.

If a value is wrong, nothing is saved and the page shows the reason: an option name that is empty, longer than 64 characters or contains < > ; = # { }, a sort order that is not a whole number, a minimum weight above the maximum weight, or an invalid tax class or geo zone. Smaller problems are saved with a remark: an invalid or negative number leaves its field empty, an invalid ship-from postcode is saved empty, and an invalid price in the table is ignored.

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, and a store without a weight class "kg".

General

Each delivery type is an option of its own at checkout. The settings on this page apply to both.

PostNL pickup point: 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 and only with an API key. Default: off.

Pickup point option name: the name customers see at checkout. Default: PostNL pickup point. Required, up to 64 characters, without < > ; = # { }.

PostNL home address: turns the home delivery option on or off. No point is chosen. It works for every country with a price. Default: off.

Home delivery option name: the name customers see at checkout. Default: PostNL. Same rules as the pickup point name.

Sort order: the position of PostNL among the shipping methods at checkout. A whole number.

Tax class: the tax class of both options. With a tax class OpenCart adds its tax on top of the prices. No tax 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 option 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 store.

Ship from (country): the country where you hand your parcels to PostNL, Netherlands or Belgium. PostNL uses the sender address for the pickup date. On install it is set to your store country if that is the Netherlands or Belgium, otherwise to the Netherlands.

Ship from (postcode): the sender postcode, for example 1234AB in the Netherlands or 1000 in Belgium. Required for pickup points: OpenCart has no store postcode, so it is not taken from the store address. 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 store default currency, tax excluded)

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

Price per country: one row per destination country. Click Add country to add a row and the × button 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" and "6,95" are accepted. Rows without prices 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 options there.

Conditions

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

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

Minimum weight (kg): hide the options when the cart weighs less. Product weights are converted from their weight class. Leave empty for no limit.

Maximum weight (kg): hide the options for heavier carts. PostNL parcels go up to 30 kg in the Benelux. 0 means no limit. If you leave it empty, 30 kg applies, or no limit when Ignore shipping zones is on.

All amounts and weights accept a decimal comma.

Availability

Geo zone: offer PostNL only for addresses in this geo zone. All zones (default) means no limit. The geo zone is not checked when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: when on, the geo zone is not checked and PostNL is offered for the countries selected below (every country when the list is empty). When off, only the geo zone counts.

Countries: the destination countries for that mode. Leave empty to allow every country. This field is used only when Ignore shipping zones is on. The pickup point option is still offered only for the Netherlands and Belgium.

Advanced

Debug log: writes debug messages to storage/logs/vfd_ptnl_debug.log.php (on OpenCart 4 system/storage/logs/vfd_ptnl_debug.log.php). The file cannot be read from the web. API errors and orders without a valid pickup point are always logged. No API key or customer data is written. Turn the log off when you are done. When the file reaches 5 MB, a new log is started.

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

Remove data on uninstall: when on, uninstalling the extension deletes the PostNL settings and the log. Cached point lists are always removed. Pickup points saved on orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the price of each PostNL option. If Ignore shipping zones is on, PostNL is offered only for an allowed country, whatever the geo zone. Otherwise, if a Geo zone is set, the address must be in it. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension checks the cart weight and the 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 option is hidden. If the cart subtotal reaches Free shipping from, the price is 0. The price is shown to the customer in their currency with the tax of the selected Tax class.

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 full postcode, the extension asks the PostNL Checkout API for the three nearest pickup points. It sends the customer's postcode, street and house number, city and country, and your ship-from address. Nothing is sent for the home delivery option. 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 cache is kept in the extension's own database table. The last error is shown on the extension page until the next successful request.

The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks a PostNL option in the window Shipping method options. The prices are the same as on OpenCart 3.

Pickup points

When the delivery address is in the Netherlands or Belgium, a PostNL pickup point list appears under the pickup point option with the three nearest points: company name, address and distance, the nearest first. The page never waits for PostNL: if the list is not cached yet, it is loaded as soon as the option 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 for the checkout right away.

The point is required. When the customer clicks Continue at the delivery method step, the server checks the point against PostNL's list for the delivery address. Without a point, the customer sees "Please choose a PostNL pickup point." If the point 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.

Order pages, e-mails and invoice: the point is added to the shipping method of the order, for example "PostNL pickup point: name, address" (the pickup point option name, then the point) (up to 128 characters, on OpenCart 4 up to 255). It is shown wherever OpenCart shows the shipping method: the customer's order history, the order e-mails, the invoice and Sales > Orders.

Admin order page: in Sales > Orders the order page shows a PostNL pickup point panel above the history with the point, the Location code and the Partner ID. It is shown only for orders with a saved point, also after the extension is disabled.

On OpenCart 4 the list of points appears in the window Shipping method options, under the PostNL pickup point option, and is loaded again each time the window opens, because the address can change on the one-page checkout. The Continue button of the window does not go on without a valid point, with the same messages. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the pickup point of the order is updated with it.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox PostNL is the first block on Extensions > Extensions > Shipping > VibeFox PostNL > Edit, 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: opencart-shipping-postnl and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 shipping options are not shown to customers at checkout and no shipping price is calculated. An admin user who is logged in to the admin in the same browser still sees the options in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the options are hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

PostNL does not appear at checkout: check that the license is active and PostNL pickup point or PostNL home address is on. Check Geo zone (or that Ignore shipping zones is on and the country is allowed), that a price is set for the country, the weight limits and Minimum subtotal. Check that the products have Requires Shipping set to Yes.

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 on top of the extension 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 extension 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 extension page warns that the store has no weight class "kg", check System > Localisation > Weight Classes. Product weights are converted by the unit name of their class, and unknown units are read as kg.

The page says "Warning: You do not have permission to modify VibeFox PostNL!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_postnl (OpenCart 3) or extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) in System > Users > User Groups.

For developers: the PostNL API address can be replaced with the setting vfd_ptnl_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox PostNL. The license key and license status of this extension are always removed. OpenCart always resets the extension status, Sort order, Tax class and Geo zone. The cached pickup point lists and the last API error are always removed. If Remove data on uninstall is on, the PostNL settings, the debug log and the points of checkouts that never became an order are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Existing orders keep their shipping method, cost and saved pickup point.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox PostNL in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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