VibeFox bpost Cubee for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
bpost Shipping Platform account (for the pickup point selector only): the module 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 carrier 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
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 bpost Cubee 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. Enter your prices and, for the pickup point selector, the bpost API keys (see Configuration). Click Save.
On install the module creates the carrier bpost parcel locker with the delivery time text Pickup point or parcel locker. The carrier is linked to the zone of Belgium and to all customer groups, without a tax rule. You can change zones, customer groups, delivery time and logo 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 bpost Cubee > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the stored API token and the cached pickup point lists.
The page shows warnings when something silently hides the carrier 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, the last connection to the bpost API failed, the shop weight unit is not known to the module (set it in International > Localization, Local units), or the bpost carrier was not found. When you save, lines of Country prices that could not be read are listed in a warning, and so is a Size prices value in which no size was recognised. A weight or amount that is not a number or is negative is not saved: a warning names the field and the previous value is kept. If Min weight (kg) is greater than Max weight (kg), the weights are not saved either.
General
Enable/Disable: turns bpost parcel locker shipping on or off. This is the same switch as the carrier status in Shipping > Carriers.
Name: the shipping method name shown to the customer at checkout (the carrier name). Default: bpost parcel locker. If you leave it empty, the default is used. At most 64 characters; a longer name is refused and nothing is saved.
Tax status: None means the prices are final. Taxable with a tax rule adds the tax of that rule on top of your prices. The choice is saved to the carrier.
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 all three API keys are 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 shop 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 carrier.
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 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 cart currency.
Conditions
Min weight (kg): the minimum cart weight for the carrier to appear. Product weights are converted from your shop weight unit. 0 means no limit.
Max weight (kg): the carrier 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 carrier only when the cart subtotal reaches this amount. The subtotal counts products that need shipping, after discounts, tax excluded. Leave it empty to always show the carrier.
Free shipping
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal (products that need shipping, after discounts, tax excluded) from which shipping is free. Used only when Free shipping is on. The country still needs a price, otherwise the carrier is not offered.
Availability without shipping zones
Normally the carrier is offered in its shipping zones in Shipping > Carriers. On install that is the zone of Belgium.
Ignore shipping zones: offer the carrier in the countries below without adding it to a zone. The carrier is then linked to all active zones, also to zones you create later. When you switch the option off again, the carrier gets its previous zones back.
Countries: the destination countries for that mode. Default: Belgium. Leave it empty to use all countries you ship to. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs API requests and price calculations to logs/vfd_bpst_debug.log.php in the module folder. The file cannot be opened 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 module deletes the module settings and the carrier. Pickup points saved in orders are always kept.
How it works at checkout
At the shipping step PrestaShop asks the module for the bpost price. Only products that need shipping count: virtual products add no weight and are not included in the order amount. The module checks the conditions: the countries of Ignore shipping zones (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 carrier the customer sees a field Postal code or city, a Search button and a pickup point list. When the customer chooses the carrier and has not searched yet, the postal code of the delivery address 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 shop language is Dutch and in French otherwise.
The customer must choose a pickup point. Without one, Continue in the delivery step shows Please select a bpost pickup point., and the Place order button is held back on the page with the same message. 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 with the cart, so a page refresh does not lose them. A new search clears the previous choice.
To list pickup points, the module 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 6 hours. 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 module tries again after 5 minutes. The API timeout is 15 seconds.
If you edit the 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 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 in the order.
Pickup points
When the order is placed, the chosen pickup point (name and address) and its ID are saved with the order. On the back office order page the block bpost pickup point shows 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 is updated at once and the page shows Pickup point updated. The change is written to the module debug log when Debug log is on. The Change link is available only when the API keys are filled in. Saving a new point needs the permission to edit orders; otherwise the page shows Permission denied. Access to the Modules pages is not needed.
If PrestaShop splits one cart into several orders, the pickup point stays with the first order. The other orders have no pickup point, and the debug log shows an error naming the first order; set the point for those parcels by hand in bpost.
Customers see the pickup point as bpost pickup point: on the order confirmation page and in the order details of their account. It is also added to the carrier name in the order confirmation e-mail. The new order e-mail to the shop (if you use the e-mail alerts module) also contains the point ID.
To offer parcel locker and home delivery together, use another carrier for home delivery in the same zone. The pickup point selector appears only under the bpost carrier.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox bpost Cubee is the first block on Modules > Module Manager > VibeFox bpost Cubee > 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-bpost-cubee 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 bpost carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier 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 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 or resetting the module 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. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or that Ignore shipping zones 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. Products can also be limited to certain carriers in the product page. 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 on the settings page and in the debug log (Log field on the module page). The module 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 status set to None the prices are final. With a Taxable tax rule PrestaShop adds that tax on top of your prices.
The page says the bpost carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
For developers, the hooks actionVfdBpstApiUrl and actionVfdBpstApiLanguage change the bpost API address and the language of the pickup point list.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox bpost Cubee and choose Uninstall. The license key and license status are always removed. The stored API token and the cached pickup point lists are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and pickup points of unfinished carts are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again gives the carrier back the status it had before the uninstall. Reset in Modules > Module Manager works the same way, so a carrier you switched off stays off. Pickup points saved in orders are order history and are never deleted.
bpost is a trademark of its respective owner. This module is not affiliated with or endorsed by bpost.