VibeFox bpost Cubee for WooCommerce — Help
Requirements
WordPress: 5.8 or later.
WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.
PHP: 8.0 or later.
bpost Shipping Platform account (for the pickup point selector only): the plugin 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 as a fixed-price shipping method, 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_bpost_cubee folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox bpost Cubee, or click Settings under the plugin name on the Plugins page.
4. Enter your VibeFox license key in the license block at the top of the page and click Activate.
5. Enter your prices and, for the pickup point selector, the bpost API keys (see Configuration).
6. Add VibeFox bpost Cubee to your shipping zone for Belgium in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.
Configuration
All settings are on one page: WooCommerce > Settings > Shipping > VibeFox bpost Cubee. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:
Title (zone): the name of this option at checkout for this zone. Leave it empty to use the global Name.
The settings page shows warnings 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, or the last connection to the bpost API failed. Every time you save the settings, the stored API token and the cached pickup point lists are cleared.
General
Enable/Disable: turns bpost parcel locker shipping on or off in all zones at once.
Name: the shipping method name shown to the customer at checkout. Default: bpost parcel locker.
Tax status: Taxable adds WooCommerce tax on top of your prices, None means the prices are final.
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.
Passphrase (private key): the private key used to sign every request (HMAC-SHA256). It is never sent to bpost or written to the log.
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 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 store currency; 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 and listed in an error message when you save. 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.
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 (excluding tax) reaches this amount. Leave empty to always show it.
Excluded shipping classes: hide the method when any cart item belongs to one of these WooCommerce shipping classes.
Product weights are converted from your store weight unit to kilograms.
Free shipping
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal (excluding tax) from which shipping is free. Used only when Free shipping is on.
Availability without shipping zones
Ignore shipping zones: offer the method in the countries below without adding it to a zone.
Countries: the destination countries for that mode. Default: Belgium. Leave 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 in WooCommerce > Status > Logs, source vfd-bpost-cubee. API errors are always logged, even when this option is off. Keys, tokens and customer data are never logged.
Remove data on uninstall: when on, deleting the plugin removes its settings and its zone methods. Deactivating the plugin never deletes data. Pickup points saved in orders are always kept.
How it works at checkout
When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. 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.
When the customer chooses the bpost rate, a search field, a Search button and a pickup point list appear under it. If the search field is empty, the postal code of the checkout 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 pickup point list is requested in Dutch on Dutch-language sites and in French otherwise.
The customer must choose a pickup point. Without one, the classic checkout shows Please select a bpost pickup point. and the block checkout refuses to place the order with the same message. The choice is kept during the checkout session, so a page refresh does not lose it.
To list pickup points, the plugin sends bpost only the searched postal code or city, the country and the carrier ID, signed with your keys. No customer name, e-mail or address line is sent. 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 plugin tries again after 5 minutes. The API timeout is 15 seconds.
The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).
The plugin 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
The chosen pickup point (name and address) and its ID are saved in the order. On the admin order screen it is shown under the shipping address as bpost pickup point. Click Change, search a postal code or city and choose another point from the list. The order is updated at once and an order note bpost pickup point changed to: … is added. The Change link is available only when the API keys are filled in.
Customers see the pickup point on the thank-you page and in My account > Orders. It is also added to the order e-mails, both HTML and plain text.
To offer parcel locker and home delivery together, add another shipping method, for example Flat rate, to the same zone. The pickup point selector appears only under the bpost rate.
License key
The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox bpost Cubee. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.
One key works on one domain. Removing the key from a site 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. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.
When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.
Troubleshooting
bpost does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check that the country has a price or that there is a *=PRICE line, and check the weight limits, Minimum order amount and Excluded shipping classes. 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 in WooCommerce > Status > Logs (source vfd-bpost-cubee) and on the settings page. The plugin 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 error message after saving lists them.
Are prices including tax? With Tax status set to Taxable WooCommerce adds tax on top of your prices. With None the prices are final.
The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.
Uninstall
Deactivating the plugin keeps all settings; it only clears the API token and the cached pickup point lists. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin, the API token and the caches are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Pickup points saved in orders are order history and are never deleted.
bpost is a trademark of its respective owner. This plugin is not affiliated with or endorsed by bpost.