VibeFox bpost Cubee for Adobe Commerce — Aide
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.
PHP: 8.1 to 8.4, with the cURL and JSON extensions.
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 ([email protected]). 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 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-bpost-cubee-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/BpostCubeeShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_BpostCubeeShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy (the module has its own checkout scripts and styles), then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox bpost Cubee. 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. Enter your prices, for example BE=4.95 in Country prices, and, for the pickup point selector, the bpost API keys (see Configuration). Set Enable bpost parcel locker shipping to Yes and click Save Config.
The module adds the bpost shipping method to Magento. Customers see it as bpost - Parcel locker or pickup point (method title and method name). It is off after installation (Enable bpost parcel locker shipping = No) and is offered for Belgium by default. The module adds one table of its own for the chosen pickup points.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox bpost Cubee, 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; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and also clears the stored API token and the cached pickup point lists. Amounts and weights accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: a Method title or Method name longer than 64 characters or with one of the characters < > ; = # { }, or a Sort order that is not a whole number. An empty Method title or Method name is saved as its default.
Other problems are saved with a warning. 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. Lines of Country prices that could not be read are removed and listed in a warning, and a warning appears when nothing was recognised in Size prices.
The group also shows notices 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), or the last connection to the bpost API failed.
General
Enable bpost parcel locker shipping: shows or hides the method at checkout. Default: No.
Method title: the carrier name shown before the method name in the cart and at checkout. Default: bpost. At most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Parcel locker or pickup point. At most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
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. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved passphrase, type a new value to change it. To delete it, clear the field (or the Account ID) and click Save Config.
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. Default: Yes. The selector appears, and a pickup point is required, only when all three API keys are filled in. Without them the method is a plain fixed-price shipping method.
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 the base currency of your store, 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. 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 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 2 decimals; Magento then shows them in the customer's currency. The module has no tax setting: if your store taxes shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
Conditions
Min weight (kg): the minimum cart weight for the method to appear. 0 means no limit.
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 discounts, tax excluded, in the base currency. Leave it empty to always show the method.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).
Free shipping
Free shipping: turns on free delivery from the amount below. Default: No.
Free shipping from: the cart subtotal (products that need shipping, after discounts, tax excluded, in the base currency) from which shipping is free. Used only when Free shipping is Yes. The country still needs a price, otherwise the method is not offered.
Availability
Ship to Applicable Countries: Specific Countries (default) offers the method only for the countries below. All Allowed Countries offers it for every country your store allows that has a price.
Ship to Specific Countries: the destination countries for Specific Countries. Default: Belgium.
Advanced
Debug log: logs API requests and price calculations to var/log/vfd_bpst_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Keys and tokens are never logged.
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 module settings, the log and the pickup point searches of carts that never became an order (see Uninstall). The license key and the cache are always removed. Pickup points saved in orders are always kept.
How it works at checkout
At the shipping step Magento asks the module for the bpost price. 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 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. A Magento cart price rule with free shipping also makes the price 0. No request goes to bpost for the price.
When the customer chooses the bpost method, a field Postal code or city, a Search button and a pickup point list appear under the shipping methods. If the customer 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 locale of the store view is Dutch and in French otherwise.
The customer must choose a pickup point. Without one, Next in the shipping step shows Please select a bpost pickup point. and the checkout stays on the shipping step; Magento checks this again on the server. 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.
The pickup point selector is made for the standard Magento checkout (Luma and Blank themes). Third-party checkouts, such as Hyvä or one-step checkouts, need their own integration.
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 is saved with the order and added to its shipping description, for example bpost - Parcel locker or pickup point - bpost pickup point: followed by the name and address of the point. The customer sees this text in the order e-mails, in the order in their account and on invoices.
On the admin order page (Sales > Orders > View, Information tab) the block bpost pickup point shows the point, its ID and the country, 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 description are updated at once and the page shows Pickup point updated. 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 your Admin role allows editing orders (Sales > Operations > Orders > Actions > Edit). The block is also shown for older orders and when the module is switched off.
An order placed without a pickup point while the selector is active, for example an order created in the Admin, has no point; the debug log shows an error for it. If the customer cancels a payment at the payment provider and the cart is restored, the customer chooses a pickup point again; the new order gets the new point, and the earlier order keeps its own.
To offer parcel locker and home delivery together, use another shipping method for home delivery. The pickup point selector appears only for the bpost method.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox bpost Cubee is the first row of the VibeFox bpost Cubee 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-bpost-cubee 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 bpost method is not shown to customers at checkout and no rate is calculated. 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
bpost does not appear at checkout: check that the license is active and Enable bpost parcel locker shipping is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, that the country has a price or that there is a *=PRICE line, the weight limits and Minimum order amount. The settings page shows a notice when Belgium has no price.
No pickup point selector at checkout: check that Pickup points is Yes and that Account ID (public key), Passphrase (private key) and App ID (X-APPID) are all filled in. The settings page shows a notice 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 in the notices of the settings group and in the debug log (Log field in the Advanced section). The module retries automatically after 5 minutes. Clicking Save Config 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 removed on save; the warning after saving lists them.
Are prices including tax? The prices are used as you enter them. If your store taxes shipping (Tax Class for Shipping), Magento adds that tax on top of them.
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 and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_BpostCubeeShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_BpostCubeeShipping to remove the data, then bin/magento module:disable Vibefox_BpostCubeeShipping, delete the folder app/code/Vibefox/BpostCubeeShipping and run bin/magento setup:upgrade.
The license key, the license status, the stored API token and the cached pickup point lists are always removed. If Remove data on uninstall is Yes, the settings, the log and the pickup point searches of carts that never became an order are removed too. If it is No, the settings are kept for a re-install. Pickup points saved in orders and the shipping descriptions of 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.