VibeFox Balikobot for Adobe Commerce — Help
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.
Balikobot account (for live rates and pickup points): you need a Balikobot account with API access. The API user and API key are in the Balikobot client zone (client.balikobot.cz). Balikobot support ([email protected]) activates the API for your account and carriers. Live rates need a carrier and service for which Balikobot supports "transportcosts". Pickup points need a carrier with "branchlocator" support (for example Česká pošta, Zásilkovna, PPL, DPD, GLS). Ask Balikobot support if unsure. Fixed prices work without an account.
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-balikobot-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/BalikobotShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_BalikobotShipping 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 Balikobot. 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 the country prices, or the API user and API key, choose the carrier and service type and the price source (see Configuration). For pickup services, set Pickup point selection to Yes. Set Enable Balikobot to Yes and click Save Config.
The module adds the Balikobot shipping method to Magento. Customers see it as Balikobot - Parcel delivery (method title and method name). It is off after installation (Enable Balikobot = No). The module adds one table of its own for the pickup points of carts and orders.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Balikobot, 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 clears the cached Balikobot rates and pickup points. 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 Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number.
Other mistakes are saved with a warning. A number field that does not contain a number of 0 or more is saved empty (Min weight (kg) and Max weight (kg) get their defaults 0 and 100). If Min weight (kg) is greater than Max weight (kg), both weights keep their previous values. Invalid rows of Country prices are removed, and the warning lists them.
At the top of the group, under the license block, warnings show settings that would hide the method, the live rates or the pickup points: live rates or pickup points without the API user or API key, a base currency other than CZK without Exchange rate, and empty Country prices with fixed prices or the fallback.
General
Enable Balikobot: shows or hides Balikobot at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: Balikobot. Required, at most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Parcel delivery. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Balikobot API account (needed for live rates and pickup points)
API user: your Balikobot API user from the client zone. Clearing it also clears the saved API key.
API key: your Balikobot API key from the client zone. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field (or clear API user) and click Save Config.
Carrier: the Balikobot carrier used for rates and pickup points: Česká pošta (default), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) or Magyar Posta. It must be activated in your Balikobot account.
Service type: the Balikobot service code of the carrier. Default: NP. For Česká pošta: NP = parcel to a post office, NB = parcel to Balíkovna, DR = home delivery. The codes of other carriers are listed in the Balikobot client zone and API documentation.
Price (all prices are in the base currency of the store, tax excluded)
Price source: how the price is calculated.
Country prices: a table of destination countries and prices. Click Add country to add a row, choose the country and enter the price; click Delete to remove a row. * All other countries is the price for every country without its own row. Decimals with a dot or a comma. Used in the fixed mode and as the API fallback. A country without a price (and without a * All other countries row) gets no fixed rate. Invalid rows are removed when you save, and a warning lists them.
Fixed price per: Order (default) charges the price once. Item (price x quantity) multiplies it by the number of items in the cart. This applies to fixed prices only. A live Balikobot rate is always for the whole package.
Exchange rate: the value of 1 unit of the Balikobot price currency (usually CZK) in the base currency of your store, for example 0.04. Used only when Balikobot returns a price in a currency other than your base currency. Leave it empty to reject such prices, so a customer is never charged a wrong price.
Shipping tax is not set in the module: if your store charges tax on shipping, choose the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Balikobot prices are usually without VAT.
Conditions
Min weight (kg): hide the method when the cart is lighter. 0 means no limit.
Max weight (kg): hide the method when the cart is heavier. Default: 100. 0 means no limit, an empty field means 100 kg.
Minimum order amount: show the method only from this subtotal of the products that need shipping (after discounts, tax excluded, base currency). Leave empty to always show it.
Free shipping: set to Yes to make shipping free from the amount below. Default: No.
Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, base currency) from which shipping is free. No request goes to Balikobot in that case.
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 only the weight is sent to Balikobot.
Availability
Ship to Applicable Countries: All Allowed Countries offers Balikobot for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries, for example Czechia, Slovakia and Hungary.
Pickup points
Pickup point selection: when Yes, the customer must choose a pickup point. Use it for pickup services, for example Česká pošta NP or NB, or Zásilkovna. Needs the API user and API key. Default: No.
Selector width: the CSS width of the pickup point list, for example 100% or 400px. Default: 100%.
Advanced
Debug log: logs API requests and rate calculations to var/log/vfd_blkb_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. Credentials and customer addresses are never logged. Turn the log off when you are done.
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 Balikobot settings, the log and the pickup points of carts that never became an order (see Uninstall). The license key and the cached rates are always removed. Pickup points saved in orders are never deleted.
How it works at checkout
At the shipping step Magento asks the module for the Balikobot price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Balikobot. A Magento cart price rule with free shipping also makes the price 0.
In the fixed mode the price is taken from Country prices. In the live modes the module sends Balikobot the carrier, the service type, the destination country and postcode, and the cart weight in kg. A live rate is requested only when the shipping address has a postcode. A price in a currency other than your base currency is converted with Exchange rate, or rejected if no rate is set. Magento then shows the price in the customer's currency and adds tax on shipping if your store charges it.
Live prices are cached for 1 hour, so the same cart does not trigger a new request. A failed request is cached for 5 minutes, and the API timeout is 12 seconds, so the checkout does not wait for Balikobot on every refresh. API errors are never shown to the customer: the method is hidden, or the fixed price is used in the fallback mode. The details go to the debug log.
The module does not create shipments in Balikobot, print labels or order pickups: order the shipment in the Balikobot client zone. It does not track parcels or update order statuses. One carrier and one service type are used for all countries. Pickup points are shown as a drop-down list, without a map.
Pickup points
With Pickup point selection set to Yes, a Pickup point list appears under the shipping methods in the shipping step while Balikobot is selected. It works in the standard Magento checkout (Luma and Blank themes); other checkout extensions need their own integration. The list is loaded from the Balikobot "branchlocator" for the country, city and postcode of the shipping address and is loaded again when the address changes. Until the address has a city, the customer sees Enter your city to see the pickup points. The list is cached for 12 hours.
The choice is saved to the cart as soon as the customer picks a point. It is required: Next in the shipping step is blocked with Please select a pickup point. The server also checks that the chosen point belongs to the shipping address. Otherwise the customer sees The selected pickup point is not available for your shipping address. Please choose a pickup point again. If no points are found, the customer is asked to check the city and postcode or choose another shipping method. If the points cannot be loaded, the customer is asked to try again later or choose another shipping method.
The chosen pickup point is added to the shipping description of the order, for example Balikobot - Parcel delivery - Pickup point: followed by the point. The customer sees it 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 Balikobot pickup point block shows the point with its Balikobot ID and the carrier, which you need when you create the shipment in Balikobot. Click Change to choose another point near the shipping address of the order and click Save; the shipping description of the order changes too. Change needs the Admin role right to edit orders (Sales > Operations > Orders > Actions > Edit) and Pickup point selection set to Yes. If a Balikobot order has no point (for example an order created in the Admin), the block shows No pickup point was selected for this order. and you can choose one with Change. The block is also shown for older orders and when the module is switched off. Existing orders keep their pickup point data.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Balikobot is the first row of the VibeFox Balikobot 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-balikobot 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 Balikobot 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
Balikobot does not appear at checkout: check that the license is active and Enable Balikobot is Yes for the website of the store. Read the warnings at the top of the VibeFox Balikobot group. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. In the fixed mode, check that the country or * All other countries has a price.
Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. It shows the reason: missing API credentials, no postcode yet, the Balikobot error for the carrier and service (for example authorization failed, check the API user and API key), or a price in another currency without Exchange rate. With Live Balikobot rate, fixed price if the API fails customers still get the fixed price while you fix the problem.
Prices are in the wrong currency: fixed prices are in the base currency of your store. Balikobot returns live prices in the currency of your Balikobot contract (usually CZK). If it differs from your base currency, set Exchange rate.
Is VAT included: Balikobot prices are usually without VAT. If your store taxes shipping (Tax Class for Shipping), Magento adds the tax.
No pickup points in the list: check that the API user and key are set, that the carrier supports "branchlocator" and that the shipping address has a city and postcode. Check the log for the Balikobot error.
Rates or pickup points look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached rates and pickup points.
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, the settings and the pickup point table stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_BalikobotShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_BalikobotShipping to remove the data, then bin/magento module:disable Vibefox_BalikobotShipping, delete the folder app/code/Vibefox/BalikobotShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached rates and pickup points are always removed. If Remove data on uninstall is Yes, the Balikobot settings, the log and the pickup points 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 never deleted.
Balikobot is a trademark of its respective owner. This module is not affiliated with or endorsed by Balikobot.