VibeFox bpost Cubee 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.
bpost Shipping Platform account (for the pickup point selector only): the extension searches pickup points through the bpost Shipping Platform API. Log in to your bpost Shipping Platform account at plugins.bpost.be and create the keys in Settings > Key management. You need three values: Account ID (public key), Passphrase (private key) and an App ID (X-APPID). The App ID is issued by bpost for your integration; ask bpost e-commerce support (eol@bpost.be). You also need the carrier ID of your contract (68 = bpost). Without complete keys the method still works with fixed prices, but customers are not asked to choose a pickup point.
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_bpost_cubee-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_bpost_cubee.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_bpost_cubee-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 the package into the root folder of your store.
2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox bpost Cubee 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. Enter your prices, for example BE=4.95 and *=9.95, and, for the pickup point selector, the bpost API keys (see Configuration). Turn on Enable/Disable and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_bpost_cubee.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 type Shipping. Find VibeFox bpost Cubee, 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 the method is off until you turn it on and save. If you install the extension again after an uninstall, the settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the stored API token and the cached pickup point lists. Only admin users with the modify permission for this extension can save the settings.
Some errors stop the save and nothing is saved: a Name longer than 64 characters, a Sort Order that is not a whole number, or an unknown tax class or geo zone. Other problems are reported as warnings and the rest is saved: a weight or amount that is not a number or is negative is not saved and the previous value is kept; if Min weight (kg) is greater than Max weight (kg), the weights are not saved; lines of Country prices that could not be read are listed and ignored; a Size prices value in which no size was recognised is reported.
The top of the page warns when something silently hides the method or the selector: the pickup point selector is on but the API keys are incomplete, there is no price for Belgium (BE) and no default price (*=PRICE), the last connection to the bpost API failed, or the store has no weight class with the unit "kg" (System > Localisation > Weight Classes). In the last case product weights are read by their unit name (kg, g, lb or oz).
General
Enable/Disable: turns bpost parcel locker shipping at checkout on or off. Default: off.
Name: the shipping method name shown to the customer at checkout. Default: bpost parcel locker. If you leave it empty, the default is used. At most 64 characters.
Tax Class: the tax of this class is added on top of your prices. --- None --- (default) means the prices are final.
Sort Order: the position of the method in the list of shipping methods.
bpost API (pickup point search) (needed only for the pickup point selector)
Account ID (public key): the public key of your bpost Shipping Platform account, from Key management at plugins.bpost.be. Clearing this field also removes the saved passphrase.
Passphrase (private key): the private key used to sign every request (HMAC-SHA256). It is never sent to bpost 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.
App ID (X-APPID): the application identifier bpost issued for your integration. It is sent in the X-APPID header.
Carrier ID: the carrier of your bpost Shipping Platform contract whose pickup points and parcel lockers are listed. Default: 68 (bpost). Other carriers enabled in your contract have their own IDs.
Pickup point selector
Pickup points: shows the pickup point and parcel locker selector at checkout. On by default. The selector appears, and a pickup point is required, only when Account ID, Passphrase and App ID are all filled in.
Search field width: the CSS width of the postal code / city field, for example 100% or 300px. Default: 100%.
Pickup point list width: the CSS width of the pickup point list, for example 100% or 400px. Default: 100%.
Prices (in your store default currency, tax excluded; bpost does not return shipping prices through this API)
Price by: how the price is chosen.
Country prices: one line per country in the form CC=PRICE, for example BE=4.95. The line *=PRICE sets the price for all other countries, for example *=9.95. Both a point and a comma are accepted as the decimal separator. Invalid lines are ignored. Countries without a price (when there is no * line) are not offered the method.
Size prices: used when Price by is parcel size, in the form S=3.50, M=4.50, L=6.00, XL=8.00. The size comes from the cart weight: S up to 2 kg, M up to 5 kg, L up to 10 kg, XL above.
Calculation: Per order (default) charges the price once. Per item (price x number of items) multiplies it by the number of items in the cart.
Prices are rounded to the decimals of your default currency and then shown in the customer's currency.
Conditions
Min weight (kg): the minimum cart weight for the method to appear. Product weights are converted to kg. 0 means no limit (default).
Max weight (kg): the method is hidden above this cart weight. Default: 30, because bpost parcel lockers accept parcels up to 30 kg. 0 means no limit.
Minimum order amount: show the method only when the cart subtotal reaches this amount. The subtotal counts products that need shipping, after coupons, tax excluded. Leave it empty to always show the method.
Free shipping
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal (products that need shipping, after coupons, tax excluded) from which shipping is free. Used only when Free shipping is on. The country still needs a price, otherwise the method is not offered.
Availability
Normally the method is offered in the geo zone selected below. With Ignore geo zone it is offered in the countries of the list instead.
Geo Zone: offer the method only for addresses in this geo zone. All Zones (default) means everywhere. Geo zones are managed in System > Localisation > Geo Zones.
Ignore geo zone: offer the method in the countries below, whatever the geo zone.
Countries: the destination countries for that mode. Default: Belgium. Leave it empty to allow all countries. Only used when Ignore geo zone is on.
Advanced
Debug log: writes API requests and price calculations to storage/logs/vfd_bpst_debug.log.php. The file cannot be read from the web. API errors are always logged, even when this option is off. Keys and tokens are never logged.
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 settings, the log and the pickup point choices of unfinished checkouts. Pickup points saved in orders are always kept. Default: off.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The passphrase 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 passphrase is kept.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the bpost price. If a Geo Zone is set (and Ignore geo zone is off) and the address is outside it, the method is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension checks the conditions: the countries of Ignore geo zone (if it is on), cart weight and minimum order amount. Then it takes the price from the country list or by parcel size, multiplies it by the number of items in the per-item mode and sets it to zero when free shipping applies. No request goes to bpost for the price.
Under the bpost option the customer sees a field Postal code or city, a Search button and a pickup point list. When the customer chooses bpost and the list is not loaded yet, the postal code of the delivery address (or the customer's last search) is searched automatically. The customer can enter another postal code or a city name. Each point is shown as its name and address. Up to 50 points are listed. The list is requested in Dutch when the store language is Dutch and in French otherwise.
The customer must choose a pickup point. Without one, Continue in the delivery method step shows Please select a bpost pickup point. Only a point from bpost's list for the search is accepted. Otherwise the customer sees The selected bpost pickup point is not in the list of your search. Please choose another one. The search and the choice are saved for the checkout, so a page refresh does not lose them. A new search clears the previous choice.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks bpost in the window Shipping method options. The pickup point search and list appear in that window under the bpost option. Continue in the window without a pickup point shows Please select a bpost pickup point. The rest works the same way as on OpenCart 3.
To list pickup points, the extension sends bpost only the searched postal code or city, the country and the carrier ID, signed with your keys. The API token is requested and renewed automatically. If bpost rejects a token, a new one is requested once and the search is repeated. Search results are cached for up to 6 hours, but not longer than the OpenCart cache lifetime (1 hour by default). If bpost does not answer, the customer sees Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. and the extension tries again after 5 minutes. The API timeout is 15 seconds.
The extension uses fixed prices only. It does not get live rates from bpost, create shipments, print labels or track parcels. Pickup points are shown as a list, not on a map. Create the shipments in your bpost Shipping Platform or Shipping Manager account; the pickup point ID is on the admin order page.
Pickup points
When the order is placed, the chosen pickup point is added to the shipping method of the order as bpost pickup point: with the point name and address, for example "bpost parcel locker - bpost pickup point: …". The customer therefore sees it on the order confirmation, in the order history of their account, in the order e-mails and on the invoice. The full point, with its ID, is also saved in a separate table of the extension. On OpenCart 4 the checkout keeps one order: when the customer confirms the order again, for example after choosing another pickup point, the point of the order is updated.
In the admin, the order page in Sales > Orders shows the panel bpost pickup point with the point and its ID, or No pickup point was selected for this order. Click Change, search a postal code or city, choose another point from the list and click Save. The order and its shipping method text are updated at once and the page shows Pickup point updated. If the point is not in bpost's list for the search, the page shows Pickup point not found in the bpost list of this search. The change is written to the debug log when Debug log is on. Change is available only when the API keys are filled in and the admin user may modify orders; access to the extension settings is not needed.
To offer parcel locker and home delivery together, use another shipping method for home delivery. The pickup point selector appears only under the bpost option.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox bpost Cubee is the first block on Extensions > Extensions > Shipping > VibeFox bpost Cubee > 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-bpost-cubee 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, bpost is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method 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 method is 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
bpost does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo Zone, or that Ignore geo zone is on and the country is in Countries. Check that the country has a price or that there is a *=PRICE line, and check the weight limits and Minimum order amount. Check that the products have Requires Shipping set to Yes. The settings page shows a warning when Belgium has no price.
No pickup point selector at checkout: check that Pickup points is on and that Account ID (public key), Passphrase (private key) and App ID (X-APPID) are all filled in. The settings page shows a warning when the keys are incomplete.
Customers see "Pickup points cannot be loaded right now": bpost did not answer or refused the keys. The reason is shown at the top of the settings page and in the debug log (Log field on the extension page). The extension retries automatically after 5 minutes. Saving the settings retries immediately.
No pickup points found for this postal code or city: bpost returned no points for that search. Ask the customer to try a nearby postal code or a city name, and check the Carrier ID.
Prices with a comma are not used: both 5,50 and 5.50 are accepted. Lines in Country prices that do not follow CC=PRICE are ignored; the warning after saving lists them.
Are prices including tax? With Tax Class set to --- None --- the prices are final. With a tax class OpenCart adds that tax on top of your prices.
The page says "Warning: You do not have permission to modify VibeFox bpost Cubee!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_bpost_cubee (OpenCart 3) or extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) in System > Users > User Groups.
For developers: the bpost API address can be replaced with the setting vfd_bpst_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 bpost Cubee. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort Order, Tax Class and Geo Zone. The stored API token and the cached pickup point lists are always removed. If Remove data on uninstall is on, the settings, the log and the pickup points of unfinished checkouts are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Pickup points saved in orders are order history and are never deleted. Existing orders keep their shipping method and cost.
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 bpost Cubee in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
bpost is a trademark of its respective owner. This extension is not affiliated with or endorsed by bpost.