VibeFox Instabee for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_instabee-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_instabee.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_instabee-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Instabee and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

5. Fill in the Prices section and, for the parcel box selector, your Budbee API key and API secret (see Configuration). Turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_instabee.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Instabee, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable/Disable and save. If you install the extension again after an uninstall, the Instabee settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached parcel box lists and the last API error. Only admin users with the modify permission for this extension can save the settings.

Warnings above the settings tell you when only one of the API credentials is entered, when there are no API credentials, when there are no country prices and no fallback cost, when the last Budbee API request failed (with date, time and reason), and when the store has no weight class with the unit kg and the unit of the default weight class is not recognised (weights are then treated as kg; add a kg weight class in System > Localisation > Weight Classes).

If Method name is empty or too long, Min weight (kg) is greater than Max weight (kg), Sort order is not a whole number, or the tax class or geo zone does not exist, nothing is saved and an error is shown.

General

Enable/Disable: shows or hides Instabee at checkout. Default: off.

Method name: the shipping method name shown to the customer at checkout. Default: Instabee parcel box. Required, at most 64 characters.

Tax class: None (the prices are final) (default) means the prices below are final. A tax class adds the shipping tax of that class on top of the prices below.

Sort order: the position of Instabee among the shipping methods at checkout. A whole number.

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.

After saving, both fields stay empty and show Saved - leave empty to keep it. Type a new value only to change it. To delete the saved credentials, tick Remove the saved API key and secret and save. When nothing is saved, the page shows No credentials saved.

Test environment: uses the Budbee staging API (api.staging.budbee.com). Turn it on only with staging credentials from Instabee. Live stores leave it off (api.budbee.com). Default: off.

Prices (the section title shows your store default currency)

All prices are in the store default currency, tax excluded. A decimal comma and a decimal point are both accepted (49,90 = 49.90). The price is shown to the customer in their currency.

Calculation type: how the price is applied.

Country prices: a table with the columns Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg and XL >5 kg. Click Add country to add a row and the × button to remove one. Choose * Any other country for a row that applies to all countries without their own row. An empty or 0 tier uses the Price column. A Price of 0 means free delivery. If the row of the country has no price for the cart weight, the * row is used, then the Fallback cost. When you save, a price that is not a number of 0 or more is cleared and a row with an unknown country is removed, and a warning lists them. Product weights are converted from their OpenCart weight class to kg.

Fallback cost: used when neither the row of the destination country nor the * row gives a price. Leave it empty to hide the method for such countries.

Conditions

Min weight (kg): hide the method below this cart weight. Default: 0 (no limit).

Max weight (kg): hide the method above this cart weight. Parcel boxes take up to about 20 kg. Default: 20. 0 means no limit. It cannot be lower than Min weight (kg).

Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which the method is free. Leave it empty to never make it free.

If a value in these fields or in Fallback cost is not a number of 0 or more, it is not saved, the previous value stays, and a warning names the field.

Availability

Geo zone: offer Instabee only for addresses in this geo zone. All zones (default) means everywhere. The geo zone is not checked when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: when on, the Geo zone is not checked and the method is offered for the countries below. When off (default), only the Geo zone applies.

Countries: the destination countries for that mode. Leave it empty to allow all countries. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes debug messages to storage/logs/vfd_ibee_debug.log.php (on OpenCart 4 system/storage/logs/vfd_ibee_debug.log.php). The file cannot be read from the web. API errors and orders placed without a box while the API was working are always logged, even when this is off. API keys and customer data are never logged. When the file reaches 5 MB, it is moved to vfd_ibee_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the settings, the cached box lists, the log and the boxes of unfinished checkouts. When off (default), the settings are kept for a re-install. Parcel boxes saved on orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key and secret are not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API key and secret are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Instabee price. With Ignore shipping zones on, Instabee is offered only when the country is allowed (the geo zone is not checked). Otherwise, if a Geo zone is set and the address is outside it, Instabee is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. The extension checks the cart weight and minimum order amount. If the subtotal reaches Free shipping from, the price is 0. Otherwise the price is taken from the Country prices row of the destination country, the * row or the Fallback cost. If there is no price, the method is hidden. The price is calculated in your default currency, rounded to its decimals, and shown in the customer's currency with the tax of the selected Tax class.

When the customer selects Instabee in the delivery method step and the API credentials are set, a Parcel box block appears under the method 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 (or press Enter). Until a postal code is entered, the block asks for one. If no boxes are found, the customer is asked to 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 for the checkout only if it is in the Budbee list for that postal code. A postal code typed without clicking Search is not used. When the customer clicks Continue in the delivery method step, the extension checks the box on the server again. Otherwise 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Instabee in the window Shipping method options. The Parcel box block appears in that window, under the Instabee option, and works the same way. The Continue button of the window does not go on without a box from the list, with the same messages.

The extension 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 checkout page itself never waits for Budbee: 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 extension does not calculate live rates, book shipments, print labels, give tracking numbers or tracking e-mails, 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 created, the box is checked once more and saved on the order. From then on the storefront cannot change it. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the box of the order is updated with it. If the customer switches that order to another shipping method, its box is removed. The box is shown in these places:

Shipping method of the order: the box is added to the method name, for example Instabee parcel box: (the method name) followed by the box name and address. This text appears on the order pages in the admin and in the customer account, in the order e-mails and on the invoice.

Admin order page (Sales > Orders): a panel Instabee parcel box with the box name, address and Box ID. If the box could not be checked at checkout, it is marked not verified (Budbee API was unavailable at checkout). If no box was chosen because the API was unavailable, the panel says Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. The panel is read only and is shown even when the method is switched off. On OpenCart 4 it is shown above History.

New order e-mail to the store: the box name with its ID, or Instabee parcel box: not chosen (Budbee API unavailable at checkout).

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Instabee is the first block on Extensions > Extensions > Shipping > VibeFox Instabee > Edit, 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: opencart-shipping-instabee and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (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 extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 shipping method is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Instabee does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo zone, or, when Ignore shipping zones is on, that the country is allowed in Countries. Check that the country has a price, or that there is a * row or a Fallback cost. Check the weight limits and Minimum order amount, and that the products have Requires Shipping set to Yes. A warning above the settings 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, and once a postal code is entered. The last API error is shown above the settings. Details are in the Log field on the extension page. 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 delivery method step: a parcel box must be chosen from the list, unless the Budbee API cannot be reached. A box that is not in the list of the searched postal code is not saved, and the customer sees This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Old box lists after a change: click Save on the extension page. This clears the cached box lists.

The page says "Warning: You do not have permission to modify VibeFox Instabee!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_instabee (OpenCart 3) or extension/vfd_instabee/shipping/vfd_instabee (OpenCart 4) in System > Users > User Groups.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Instabee. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax class and Geo zone. The cached box lists are always removed. If Remove data on uninstall is on, the settings, the log and the boxes chosen in checkouts that never became orders are removed as well. If it is off, the other settings are kept and are used again when you install the extension again. Parcel boxes saved on orders are always kept, and existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Instabee in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Instabee and Budbee are trademarks of their respective owners. This extension is not affiliated with or endorsed by Instabee or Budbee.