VibeFox Balikobot 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.

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 (podpora@balikobot.cz) 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

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_balikobot folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Balikobot, 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 the API user and API key, choose the carrier and service type, the price source and the country prices (see Configuration). For pickup services, turn on Pickup point selection.

6. Add VibeFox Balikobot to a shipping zone (for example Czechia) 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 Balikobot. They apply to every shipping zone. Warnings about settings that would hide the method, the live rates or the pickup points are shown at the top of the page. Every time you save the settings, the cached rates and pickup points are cleared. When you add the method to a zone, the zone window has only one field:

Title (zone): the shipping method name shown to customers in this zone. Leave it empty to use the global Name.

General

Enable/Disable: turns Balikobot shipping on or off in all zones at once.

Name: the shipping method name shown to customers. A zone can override it with its own Title. Default: Balikobot.

Tax status: Taxable means WooCommerce adds shipping tax on top of the price, None means it does not. Balikobot prices are usually without VAT.

Balikobot API account (needed for live rates and pickup points)

API user: your Balikobot API user from the client zone.

API key: your Balikobot API key from the client zone.

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 your store currency)

Price source: how the price is calculated.

Country prices: a fixed price per destination country (2-letter code, for example CZ, SK). Use * for all other countries. 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 * row) gets no fixed rate.

Fixed price per: Order charges the price once. Item (price × 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 your store currency, for example 0.04. Used only when Balikobot returns a price in a different currency. Leave it empty to reject such prices, so a customer is never charged a wrong price.

Conditions

Min weight (kg): hide the method when the cart is lighter. 0 means no limit. Product weights are converted from your store weight unit.

Max weight (kg): hide the method when the cart is heavier. Default: 100. 0 means no limit.

Minimum order amount: show the method only from this cart subtotal (after discounts, without tax). Leave empty to always show it.

Excluded shipping classes: hide the method if the cart contains a product from any of these WooCommerce shipping classes.

Free shipping: turn on free shipping from the amount below.

Free shipping from: the cart subtotal (after discounts, without tax) from which shipping is free. No API request is made in that case.

Availability without shipping zones

Ignore shipping zones: offer the method in the countries below even if it is not added to the matching zone.

Countries: the destination countries for that mode. Leave empty to use all countries you ship to. Used only with Ignore shipping zones.

Pickup points

Pickup point selection: 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.

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 WooCommerce > Status > Logs, source "vfd-balikobot". API errors are always logged. Credentials and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes its settings and zone methods. Deactivating the plugin never deletes data. Pickup points saved in orders are kept.

How it works at checkout

When the customer enters a delivery address, the plugin checks the cart weight, Minimum order amount and Excluded shipping classes. If free shipping applies, the rate is 0 and no request goes to Balikobot.

In the fixed mode the price is taken from Country prices. In the live modes the plugin sends Balikobot the carrier, the service type, the destination country and postcode, and the cart weight in kg. A live rate is requested only after the customer has entered a postcode. A price in another currency is converted with Exchange rate, or rejected if no rate is set.

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 log.

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 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 zones. Pickup points are shown as a drop-down list, without a map.

Pickup points

With Pickup point selection on, a list of pickup points appears under the Balikobot option at checkout, in the classic checkout and in the block checkout. The list is loaded from the Balikobot "branchlocator" for the customer's country, city and postcode. Until the city and postcode are entered, the customer sees Enter your city and postcode to see the pickup points. The list is cached for 12 hours.

The choice is required: the customer sees Please select a pickup point. The server also checks that the chosen point belongs to the shipping address. After an address change, the customer is asked to choose a pickup point again. If the points cannot be loaded, the customer is asked to try again later or choose another shipping method.

The chosen pickup point is saved in the order. In the admin order screen it is shown under the shipping address as Balikobot pickup point, with the Balikobot branch ID and the carrier, which you need when you create the shipment in Balikobot. Click Change to choose another point near the order address. The customer sees the point as Pickup point on the order page and in order e-mails (HTML and plain text). Existing orders keep their pickup point data.

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 Balikobot. 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, Balikobot 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

Balikobot 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). Read the warnings at the top of the settings page. Check the weight limits, Minimum order amount and Excluded shipping classes. In the fixed mode, check that the country or * has a price.

Live rates do not appear: turn on Debug log, reload the checkout and open WooCommerce > Status > Logs (source "vfd-balikobot"). It shows the reason: missing API credentials, no postcode yet, the Balikobot error for the carrier and service, 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 your store currency. Balikobot returns live prices in the currency of your Balikobot contract (usually CZK). If it differs from your store currency, set Exchange rate.

Is VAT included: Balikobot prices are usually without VAT. With Tax status set to Taxable WooCommerce adds shipping tax.

No pickup points in the list: check that the API user and key are set, that the carrier supports "branchlocator" and that the customer has entered a city and postcode. Check the log for the Balikobot error.

Rates or pickup points look outdated after a change: save the settings page. This clears the cached rates and pickup points.

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 and only clears the caches. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached rates and pickup points 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 point data saved in orders is never deleted.

Balikobot is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Balikobot.