VibeFox Instabee for Adobe Commerce — Guida
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.
Budbee API credentials (for parcel box selection only): an API key and an API secret. Instabee issues them to merchants with a delivery agreement. Ask your Instabee contact or use the Instabee merchant portal. The API documentation is on developer.budbee.com. Without credentials the method still works with fixed prices, but customers do not choose a parcel box.
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-instabee-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/InstabeeShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_InstabeeShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Instabee. 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. Fill in the Prices section and, for the parcel box selector, your Budbee API key and API secret (see Configuration). Set Enable Instabee to Yes and click Save Config.
The module adds the Instabee shipping method to Magento. Customers see it as Instabee - Instabee parcel box (carrier title and method name). It is off after installation (Enable Instabee = No). The module also creates its own table for the parcel boxes chosen in carts and orders.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Instabee, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. The license block is shown in the Default Config only, and Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached parcel box lists and the last API error. Amounts accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Carrier title or Method name, longer than 64 characters or with one of the characters < > ; = # { } (Enter a valid method title or name (64 characters max).); a Sort order that is not a whole number; a Minimum weight (kg) greater than the Maximum weight (kg). A price, weight or amount field that does not contain a number of 0 or more is not saved: the previous value is kept and a warning says so, while the other fields are saved.
The Information row at the top of the group shows warnings: when only one of the API credentials is entered, when there are no API credentials (the method then works with fixed prices only), when there are no country prices and no price for countries not in the table (the method is not shown at checkout), and when the last Budbee API request failed, with the date, time and reason.
General
Enable Instabee: shows or hides Instabee at checkout. Default: No.
Carrier title: the carrier name shown in the cart and at checkout. Default: Instabee. Required, at most 64 characters.
Method name: shown after the carrier title, as "Carrier title - Method name". Default: Instabee parcel box. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Parcel box selector (Budbee API)
With API credentials the customer picks a parcel box near their postal code at checkout, and the box is saved on the order. Both fields are needed. The selector stays off until both are set.
API key: your Budbee API key (the HTTP Basic user name).
API secret: your Budbee API secret (the HTTP Basic password). It is never written to the log.
Magento stores both values encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved value, clear the field and click Save Config.
Test environment: Yes uses the Budbee staging API (api.staging.budbee.com). Turn it on only with staging credentials from Instabee. Live stores leave it at No (api.budbee.com). Default: No.
Prices
All prices are in the base currency of your store, tax excluded. Magento shows the price in the customer's currency. The module has no tax field: if your store charges tax on shipping, set it in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
Country prices: a table with the columns Country, Base, XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (over 5 kg). Click Add country to add a row and Delete to remove one. Choose * All other countries for a row that applies to all countries without their own row. An empty or 0 tier uses the Base column. A Base of 0 means free delivery. If the row of the country has no price for the cart weight, the * All other countries row is used, then the Price for countries not in the table. If a country has several rows, the first one is used. When you save, rows with an invalid country are removed, prices that are not numbers are cleared, and the warning Country prices: invalid countries were removed and invalid prices were cleared. is shown.
Price for countries not in the table: used when neither the row of the destination country nor the * All other countries row gives a price. Leave it empty to hide the method for such countries.
Price applies: how the price is applied.
Conditions
Minimum weight (kg): hide the method below this cart weight. Default: 0 (no limit).
Maximum weight (kg): hide the method above this cart weight. Parcel boxes take up to about 20 kg. Default: 20. 0 means no limit, an empty field means 20 kg.
Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to always show it.
Free shipping from: the cart subtotal (after discounts, before tax, in the base currency) from which the method is free. Leave empty to never make it free.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so volumetric weight is not calculated.
Ship to Applicable Countries: All Allowed Countries offers Instabee for every country your store allows, Specific Countries only for the countries below. Default: Specific Countries.
Ship to Specific Countries: the destination countries for Specific Countries. Default: Sweden, Finland, Denmark, the Netherlands and Belgium. You can add other countries for fixed-price delivery, but the parcel box selector works only for these five countries.
Advanced
Debug log: writes rate calculations and Budbee requests to var/log/vfd_ibee_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. API keys and customer postal codes 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 Instabee settings, the log and the parcel boxes chosen in carts that never became orders (see Uninstall). The license key and the cached box lists are always removed. The parcel boxes of orders are never deleted.
How it works at checkout
At the shipping step Magento asks the module for the Instabee price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. The module checks the countries, the cart weight and Minimum order amount. If the cart subtotal reaches Free shipping from, the price is 0. Otherwise the price is taken from the Country prices row of the destination country, the * All other countries row or the Price for countries not in the table. If there is no price, the method is hidden. A Magento cart price rule with free shipping makes an available Instabee price 0.
When the customer selects Instabee and the API credentials are set, an Instabee parcel box block appears under the shipping methods for Sweden, Finland, Denmark, the Netherlands and Belgium. It lists the boxes near the postal code of the delivery address, sorted by distance, with the name, the address and the distance. The customer can type another Postal code and click Search, then choose a box in the list. If no boxes are found, the customer sees No Instabee parcel boxes were found near this postal code. Try another postal code or choose another shipping method. For other countries the method is offered without a box.
A parcel box is required. The chosen box is saved to the cart only if it is in the Budbee list for that postal code; otherwise the customer sees This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again. When the customer clicks Next, the module checks the box on the server again, and once more when the order is placed. Without a box the customer sees Please choose an Instabee parcel box. The box name is taken from the Budbee list, not from the browser. If the customer changes the delivery country or postal code of the address, the earlier choice is dropped.
The module sends Budbee only the destination country and postal code, never names, addresses, e-mails or order data. Box lists are cached for 12 hours per postal code, a postal code without boxes for 1 hour, and a failed request for 5 minutes, so a slow or broken API does not slow down every checkout refresh. The list is loaded in the background once the method is selected. The API timeout is 10 seconds.
If the Budbee API cannot be reached, the customer sees Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. The order is then flagged, and you choose the box when you book the shipment. A box chosen earlier that cannot be checked at that moment is kept and marked as not verified.
The selector works in the standard Magento checkout (Luma). The module does not calculate live rates, book shipments, print labels, give tracking numbers, offer Budbee Home delivery time slots or show a map. Book the parcel for the chosen box in your Instabee / Budbee merchant tools.
Pickup points
When the order is placed, the box is saved on the order. From then on the storefront cannot change it, and the Admin has no field to change it either. The box is shown in these places:
Shipping description of the order: the module adds Instabee parcel box: and the box name and address to the shipping method of the order. The customer sees it in the order in their account (or on the Orders and Returns page for guests) and in the order e-mails, and you see it on the admin order page. If no box was chosen because the API was unavailable, the text is Instabee parcel box: not chosen (Budbee API unavailable at checkout).
Admin order page: on Sales > Orders > View, Information tab, the Instabee parcel box block shows the box name and address and the box ID. A box that could not be checked at checkout is marked The chosen box was not verified because Budbee was unavailable. The block also works for older orders and when the module is switched off.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Instabee is the first row of the VibeFox Instabee 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-instabee 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 Instabee 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
Instabee does not appear at checkout: check that the license is active and Enable Instabee is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Check that the country has a price, or that there is a * All other countries row or a Price for countries not in the table. A warning in the Information row tells you when no price is configured. Turn on Debug log to see the reason in the Log field.
Customers do not see the parcel box list: the list appears only when both API key and API secret are set, for Sweden, Finland, Denmark, the Netherlands and Belgium. The last API error is shown in the Information row. Details are in the Log field in the Advanced section. Turn on Debug log for more detail.
HTTP 401 or 403 in the log: Budbee rejected the API key or secret. Check them, and check that Test environment matches your credentials (staging credentials only with the test environment on).
No boxes for a postal code: Budbee does not serve that postal code. The customer can search another postal code or choose another shipping method.
The customer cannot continue from the shipping step: a parcel box must be chosen from the list, unless the Budbee API cannot be reached. The customer sees Please choose an Instabee parcel box.
An order created in the Admin with Instabee is refused: the Admin shows Please choose an Instabee parcel box. While the parcel box selector is on, a box is required for Sweden, Finland, Denmark, the Netherlands and Belgium, and it can be chosen only in the storefront checkout. Use another shipping method for such Admin orders.
Old box lists after a change: click Save Config on the Delivery Methods page. This clears the cached box lists.
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_InstabeeShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_InstabeeShipping to remove the data, then bin/magento module:disable Vibefox_InstabeeShipping, delete the folder app/code/Vibefox/InstabeeShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached box lists are always removed. If Remove data on uninstall is Yes, the Instabee settings, the log and the parcel boxes chosen in carts that never became orders are removed too. If it is No, the settings are kept for a re-install. The parcel boxes of orders are never deleted, and the box stays in the shipping description of each order.
Instabee and Budbee are trademarks of their respective owners. This module is not affiliated with or endorsed by Instabee or Budbee.