VibeFox The Courier Guy 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.

ShipLogic API key (for live rates and lockers): The Courier Guy runs on the ShipLogic platform. Create an API key in your The Courier Guy courier portal under Settings > API Keys (business account). Without the key only the price table is used and the locker option is not offered.

Shipping to South Africa: live rates and lockers are for South African addresses only. South Africa must be an enabled country of the store (System > Localisation > Countries), and the live courier rate needs the South African provinces (zones), which OpenCart 3 already has.

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_the_courier_guy-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_the_courier_guy.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_the_courier_guy-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 The Courier Guy 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. Turn on Courier to the door and/or TCG locker and enter the ShipLogic API key. For live rates fill in the sender address (street, city, province, postal code) and, if your store currency is not ZAR, the ZAR conversion rate.

6. Fill in the price table and/or a fallback cost and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_the_courier_guy.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 The Courier Guy, click Install (the green + button), then Edit (the pencil button).

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

After install both options are off until you turn one on and save. The extension is enabled while at least one of the two options is on. If you install the extension again after an uninstall, the settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save clears the cached rates, lockers and the last ShipLogic error. Only admin users with the modify permission for this extension can save the settings.

If an option name, the tax status, the sort order or the geo zone is not valid, nothing is saved and the page shows the reason, for example Enter a valid option name (1-64 characters, without < > ; = # { }). A number that is not valid (for example negative) is not saved: the page names the field and keeps the previous value, and the rest is saved. While at least one option is on, warnings at the top of the page tell you when South Africa is not an enabled country, the API key is missing, the ZAR conversion rate or the sender address is missing, there is no price table and no fallback cost, South Africa has no zones (provinces), or the last ShipLogic request failed (with its date and error). A warning also appears when the store has no weight class with the unit kg or no length class with the unit cm.

General

Each delivery type is an option of its own at checkout.

Courier to the door: offers The Courier Guy courier delivery to the customer's address. Default: off.

Courier option name: the name of the courier option at checkout. Default: The Courier Guy. Required, at most 64 characters, without < > ; = # { }.

TCG locker: the customer chooses a locker at checkout. It is offered only for South African addresses and only with the ShipLogic API key. Default: off.

Locker option name: the name of the locker option at checkout. Default: The Courier Guy locker. Same rules as the courier name.

Tax status: the tax class of both options. With a tax class, live rates are taken without VAT and OpenCart adds the tax of the class. None (live rates including VAT) (default): live rates are taken including VAT.

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

ShipLogic API

API key: your ShipLogic API key from the The Courier Guy portal. It is never shown to customers or written to the log. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it. Tick Remove the saved API key and save to remove it.

Account ID: optional. The numeric ShipLogic account ID, only if your key has access to several accounts. A value that is not a number is not saved.

Live rates (for South African addresses; if no live rate is available, the price table is used)

The live rate is the cheapest ShipLogic service from your sender address to the customer's address (courier) or to the locker nearest the customer's city (locker). It needs the API key, the sender address and, for stores not in rand, a conversion rate.

Price source: where the price comes from.

ZAR conversion rate: ShipLogic quotes in South African rand (ZAR). If your store default currency is not ZAR, enter how much 1 ZAR is in your currency, for example 0.05. It must be greater than 0. Without it, live rates are not used and the price table applies. If your store currency is ZAR, leave it empty. The rate is not updated automatically.

Sender address (where The Courier Guy collects the parcels, in South Africa)

The OpenCart store address is free text, so the sender address is entered here. Street, city, province and postal code are needed for live rates.

Sender company: your company name.

Sender street address: for example 12 My Road.

Sender suburb: the suburb of the sender address.

Sender city: the city of the sender address.

Sender province: choose one of the 9 South African provinces from the list.

Sender postal code: the postal code of the sender address.

Price table (your own prices in the store default currency, tax excluded: used with Price table only, outside South Africa and whenever no live rate is available; a decimal comma or point is accepted)

Calculation type: applies to the price table only. A live rate is always for the whole order.

Prices by weight: a table of countries with a Price column and weight tiers XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (above 5 kg). Click Add row to add a row (a new row starts with South Africa) and the remove button to delete one. An empty or 0 tier uses the Price column. A price of 0 means free shipping. The row * Any country applies to countries without their own row and to a country row without any price. A price that is not a number is cleared, and the page lists it.

Fallback cost: used when there is neither a live rate nor a table price. Leave it empty to hide the options in that case.

Conditions (both options)

Min weight (kg): hide the options below this cart weight. 0 means no limit (default).

Max weight (kg): hide the options above this cart weight. Default: 30. 0 means no limit, empty means 30 kg. If Min weight (kg) is greater than Max weight (kg), the page shows a warning and both limits keep their previous values.

Minimum order amount: show the options only from this cart subtotal (products that need shipping, tax excluded, after discounts). Leave it empty to always show them.

Free shipping from: the cart subtotal from which delivery is free. Leave it empty to never offer free shipping. When the subtotal reaches it, the options are shown with a price of 0 and no request goes to ShipLogic for the rate.

Availability

Geo zone: offer the options only for addresses in this geo zone. All zones (default) means every address. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: for the delivery type below the geo zone is not checked. Instead, the option is offered in the countries below.

Delivery type without zones: Courier to the door (default) or TCG locker (customer chooses a locker). Used only with Ignore shipping zones. The other type still follows Geo zone.

Countries: the destination countries for that mode. Used only with Ignore shipping zones. Leave it empty to allow every country. Lockers are offered in South Africa only.

Advanced

Debug log: writes debug messages to storage/logs/vfd_tcgr_debug.log.php. The file cannot be read from the web. API errors are always logged, even when this option is off. The API key and customer data are never logged. When the file reaches 5 MB, 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 log and the locker choices of checkouts without an order. Cached rates and lockers are always removed. Lockers and tracking references saved on orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key is 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 is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the price of each option. The option must pass the Geo zone (or, with Ignore shipping zones, the country list). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the conditions: cart weight and minimum order amount. The order amount is the price of the products that need shipping, before tax and after the coupon discount. If free shipping applies, the price is 0.

Courier to the door: the extension asks ShipLogic for the cheapest service from your sender address to the customer's address. The address must have a street, city, province and postal code. Until then the price table is used.

TCG locker: the live rate is the cheapest door-to-locker service to the locker nearest the customer's city. It is not recalculated for the locker the customer picks. The locker option appears only for South African addresses and only with the API key.

The whole order is quoted as one parcel: the total weight, the longest length and width, and the heights stacked. Products without dimensions count as 10 cm cubes. Weights and dimensions are converted from the weight and length classes of the products. The rand amount is converted to your default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected tax class.

ShipLogic requests time out after 12 seconds. Rates are cached for 1 hour, lockers for 6 hours and failures for 10 minutes, so a slow API does not slow down every checkout refresh. If there is no live rate, the price comes from the table, then from Fallback cost. If neither applies, the option is hidden. API errors are never shown to the customer.

The extension does not book shipments, create waybills or labels, or update tracking automatically. There is no locker map: lockers are chosen from a list. Live rates and lockers are for South Africa only. Other countries get the price table. Only one rate per option (the cheapest service level) is shown, with no choice of service levels, insurance or extras at checkout.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks the courier or the locker option in the window Shipping method options. The method works the same way as on OpenCart 3.

Pickup points

When the customer chooses the locker option at the delivery method step, a locker selector appears under it: a search field (by default the city of the delivery address) and a list of lockers with name, address and opening hours. The customer can type another city, suburb or postal code and click Search. A locker must be chosen before the customer can continue: otherwise the step shows Please choose a The Courier Guy locker.

The locker is checked on the server against ShipLogic's list, when the customer continues and again when the order is placed. Its name and provider are taken from ShipLogic, never from the browser. The choice belongs to the country and city or postal code of the address: when the delivery address changes, the customer chooses again.

If ShipLogic cannot be reached, the selector says Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. The order can then be placed without a locker. It is flagged on the admin order page: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

On OpenCart 4 the locker selector appears in the window Shipping method options, under the locker option, and is loaded again each time the window opens, because the address can change on the one-page checkout. The Continue button of the window does not go on without a locker from the list, with the same message, and an unavailable ShipLogic does not block the order either. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the locker of the order is updated with it.

Orders

The chosen locker is added to the shipping method of the order, for example "The Courier Guy locker: name — address". This text appears in Sales > Orders, on the customer's order page, on the invoice and in the order e-mails.

The order page in Sales > Orders has a The Courier Guy panel above the history for every order shipped with The Courier Guy. For a locker order it shows the locker name, ID and provider, with not verified (ShipLogic was unavailable at checkout) when the locker could not be checked, or the Not chosen message when ShipLogic was unavailable. The panel is shown even while the extension is disabled.

The Courier Guy tracking reference: book the parcel in your The Courier Guy portal, enter its reference in this field of the panel and click Save. Clear the field and save to remove it. Admin users without the permission to modify orders see the reference read-only. The customer sees the reference on the order page of the account (registered customers) and in the order status e-mails when you notify the customer. The new order e-mail has no reference, because it is entered later.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox The Courier Guy is the first block on Extensions > Extensions > Shipping > VibeFox The Courier Guy > 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-the-courier-guy 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, neither The Courier Guy option (courier to the door or TCG locker) is 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 options 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 options are 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

The Courier Guy does not appear at checkout: check that the license is active and the option is switched on (Courier to the door or TCG locker). Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum order amount. Check that the table or Fallback cost has a price. Check that the products have Requires Shipping set to Yes. The locker option appears only for South African addresses and with the API key.

Customers see no locker list: lockers need the API key, TCG locker switched on and a South African delivery address. The settings page shows the last ShipLogic error, if any, for example a refused key.

The price is always the table price: check the warnings on the settings page. A live rate needs the API key, the complete sender address and, for stores not in rand, the ZAR conversion rate. For courier delivery the customer's address needs a street, city, province (zone) and postal code. For lockers ShipLogic must find a locker near the customer's city. Turn on Debug log, reload the checkout and look at the Log field on the extension page.

ShipLogic is down: the table or fallback price is shown. Locker orders can be placed without a locker and are flagged on the order.

Rates look outdated after a change: click Save on the extension page. This clears the cached rates and lockers.

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

For developers: the ShipLogic API address can be replaced with the setting vfd_tcgr_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox The Courier Guy. The license key and license status of this extension are always removed. OpenCart always resets the extension status, Sort order, Tax status and Geo zone. The cached rates and lockers and the last ShipLogic error are always removed. If Remove data on uninstall is on, the settings, the log and the locker choices of checkouts without an order are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Lockers and tracking references saved on orders are never removed, 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 The Courier Guy in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

The Courier Guy and ShipLogic are trademarks of their respective owners. This extension is not affiliated with or endorsed by The Courier Guy or ShipLogic.