VibeFox PostNord 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.

PostNord API key (for the service point picker): create a free account on developer.postnord.com, add an application and copy its API key. Without a key the shipping method still works, but customers cannot pick a service point.

PostNord agreement: to send parcels you need your usual PostNord customer agreement, for example MyPack Collect or MyPack Home.

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_postnord-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_postnord.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_postnord-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 PostNord 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 Enable/Disable (service point delivery) and/or Home delivery, paste the PostNord API key, choose the Agreement country, fill in the Country prices or a Fallback cost (see Configuration) and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_postnord.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 PostNord, 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 PostNord settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox PostNord > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached service point lists. 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: a name that is empty, longer than 64 characters or contains < > ; = # { }, a sort order that is not a whole number, an invalid tax status or geo zone, or a Min weight (kg) greater than Max weight (kg). A number field with a value that is not a number of 0 or more is saved empty, with a message. A price table cell that is not a number of 0 or more is saved as 0, with a message.

Above the settings the page warns when there is no API key yet, when there is no price yet, and when the store has no weight class "kg".

General

The two delivery options are offered in the geo zone set in Availability, or for the countries of Ignore shipping zones.

Enable/Disable: turns PostNord delivery to a service point or parcel locker on or off. The customer picks the point at checkout. Default: off.

Name: the name of the service point option at checkout, for example "PostNord MyPack Collect". Default: PostNord. Required, up to 64 characters, without < > ; = # { }.

Home delivery: also offer PostNord home delivery, a second option without a service point. Default: off.

Home delivery name: the name of the home delivery option at checkout, for example "PostNord MyPack Home". Default: PostNord Home delivery. Same rules as Name.

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

Tax status: None (the prices are final) (default), or a tax class: OpenCart then adds the shipping tax of that class on top of the prices. It applies to both options.

PostNord API (service point picker)

API key: the API key of your application on developer.postnord.com. It is sent to PostNord only from your server, never to the browser, and is never 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.

Test mode: uses the PostNord test environment (atapi2.postnord.com). Only for keys issued for the test environment.

Agreement country: the country of your PostNord customer agreement: Sweden, Denmark, Norway or Finland. It decides which service points are offered. Same as the delivery country (default) uses the customer's country.

Prices

The section title shows your store default currency. Prices are in that currency, tax excluded, and the same for both options. PostNord has no public price API, so you set your own prices, typically your PostNord agreement prices. The order is: free shipping threshold, then the country table, then the fallback cost.

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

Country prices: a price by destination country and cart weight. Click Add country to add a row and the × button to remove one. Each row has a Price and weight columns: 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 column with 0 uses the Price column, and a Price of 0 means free shipping. Country * All other countries covers every country without its own row. Decimals with a comma or a dot (9,99 or 9.99). A new row starts as * All other countries with all prices at 0. Choose the country and enter the prices before you save, or remove the row. An empty cell is saved as 0.

Fallback cost: used when the country table has no row for the destination and no * row. Leave it empty to hide PostNord for such countries.

Free shipping from: the cart subtotal (products that need shipping, after the coupon, excluding tax) from which PostNord is free. It is checked before the country table, so it also applies to a country without a price row. Leave it empty to never offer free shipping.

Availability

Min weight (kg): hide PostNord when the cart weighs less. Product weights are converted from their weight class. Default: 0, which means no limit.

Max weight (kg): hide PostNord when the cart weighs more. Default: 30. 0 means no limit. Check the weight limit of your PostNord service: parcel lockers accept less than service points.

Minimum subtotal: show PostNord only if the cart subtotal (products that need shipping, after the coupon, excluding tax) is at least this amount. Leave it empty to always show it.

Geo zone: offer PostNord only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used while Ignore shipping zones is on.

Ignore shipping zones: when on, the geo zone is not checked and PostNord is offered for the countries below. When off, it is offered only in the geo zone.

Countries (Ignore shipping zones): the destination countries for that mode. Leave it empty to allow all countries. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations and API calls to storage/logs/vfd_ptnd_debug.log.php. The file cannot be read from the web. API errors are always logged. The API key is never logged. 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 PostNord settings and the log. Cached service point lists are always removed. Service points saved in 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 PostNord option. 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 geo zone or the country list, the cart weight and the minimum subtotal. If free shipping applies, the price is 0. Otherwise the price comes from the country table, then from the fallback cost. If there is no price, the option is hidden. The price is calculated in your default currency and shown to the customer in their currency with the tax of the selected Tax status. The price calculation never contacts PostNord.

For the service point option and a delivery address in Sweden, Denmark, Norway or Finland, your server asks the PostNord Business Location API for the 10 service points nearest to the delivery postcode. It sends the delivery country and postcode and the agreement country. The API timeout is 10 seconds. Lists are cached for 6 hours per postcode, and "no points" answers for 1 hour. API errors are cached for 5 minutes, so a PostNord outage does not slow down every checkout update. The cache is kept in the extension's own database table. The delivery step never waits for PostNord: when the list is not cached yet, it is loaded after the customer selects the option.

For other destinations the options can still be offered with your prices, without a picker. The home delivery option never shows a picker.

The extension does not request live PostNord prices and does not create shipping labels, book shipments (EDI), provide tracking numbers or send tracking e-mails. There is no map view. Use PostNord Portal, Skicka Direkt Business or a label tool for shipments; the saved service point ID is what those tools need.

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

Pickup points

When the delivery address is in Sweden, Denmark, Norway or Finland, a PostNord service point list appears under the service point option with the nearest points, grouped by city, each with its address and distance. Before a postcode is entered, the customer sees "Enter your postcode to choose a PostNord service point." The choice is saved for the checkout right away.

When the list is loaded, a point is required. Without one, Continue at the delivery method step stops with "Please select a PostNord service point." The chosen point is checked on the server against PostNord's list for the delivery address. A point chosen for another postcode is not used.

The picker never blocks a sale. If the list cannot be loaded (no API key yet, PostNord API down, no points near the postcode), the customer sees a note and can still place the order. PostNord then delivers to the service point nearest to the address.

Order pages, e-mails and invoice: the point is added to the shipping method of the order, for example "PostNord: name, address (ID 12345)" (the option name, then the point). If the text would be longer than 128 characters, the address is left out (OpenCart 4 has no such limit and always keeps the address). It is shown wherever OpenCart shows the shipping method: the customer's order history, the order e-mails, the invoice and Sales > Orders. An order without a point keeps the plain method name.

Admin order page: in Sales > Orders the order page shows a PostNord service point panel above the history with the name, address and Service point ID. If no point was chosen, it says "not selected - PostNord delivers to the service point nearest to the shipping address".

On OpenCart 4 the list of service points appears in the window Shipping method options, under the service 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 point from the list, with the same message. If the customer clicks it while the list is still loading, the window waits for the list without a message and then clicks Continue again by itself. An unavailable list does not block the order either. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the service 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 PostNord is the first block on Extensions > Extensions > Shipping > VibeFox PostNord > 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-postnord 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 PostNord 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

PostNord does not appear at checkout: check that the license is active and Enable/Disable (or Home delivery) is on. Check Geo zone, or the Countries list when Ignore shipping zones is on. Check that a price is set for the country (country row, * row or Fallback cost), the weight limits and Minimum subtotal. Check that the products have Requires Shipping set to Yes.

The picker says service points cannot be loaded: check the API key and the Test mode setting. A production key does not work against the test environment, and the other way round. Turn on Debug log, reload the checkout and look at the Log field on the extension page. The order can still be placed; PostNord then delivers to the nearest service point.

Unexpected service points: check Agreement country. It decides which service points are offered.

Shipping is free by mistake: check Country prices for rows with a Price of 0, especially a * row added with Add country and left unfilled, and check Free shipping from.

Service points look outdated after a change: click Save on the extension page. This clears the cached lists.

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 PostNord!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_postnord (OpenCart 3) or extension/vfd_postnord/shipping/vfd_postnord (OpenCart 4) in System > Users > User Groups.

For developers: the PostNord API address can be replaced with the setting vfd_ptnd_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 PostNord. The license key and license status of this extension are always removed. OpenCart always resets the extension status, Sort order, Tax status and Geo zone. The cached service point lists are always removed. If Remove data on uninstall is on, the PostNord settings, the debug log and the service 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 service 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 PostNord in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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