VibeFox The Courier Guy for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 carrier is not offered.

Shipping to South Africa: live rates and lockers are for South African addresses only. South Africa must be an active country of the shop (International > Locations > Countries).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox The Courier Guy in the module list later and click Configure.

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

4. Enter the ShipLogic API key. For live rates fill in the sender address (street, city, province, postal code) and, if your shop currency is not ZAR, the ZAR conversion rate.

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

6. For live courier rates, click Add South African provinces in the Advanced section if the page says that South African addresses have no province.

On install the module creates two carriers: The Courier Guy (delivery time text The Courier Guy courier delivery to your door) and The Courier Guy locker (Delivery to a TCG locker of your choice). Both are active, linked to the zone of South Africa and to all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox The Courier Guy > Configure. Each section has its own Save button, which saves the whole page. Every save clears the cached rates, lockers and the last ShipLogic error. Warnings at the top of the page tell you when South Africa is not an active 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 African addresses have no province, the shop weight or dimension unit is not known to the module, or the last ShipLogic request failed (with its date and error). A number that is not valid (for example negative) is not saved: the page names the field and keeps the previous value.

General

Courier to the door: turns the courier carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Courier carrier name: the name of the courier carrier at checkout. Default: The Courier Guy. Required.

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

Locker carrier name: the name of the locker carrier at checkout. Default: The Courier Guy locker. Required.

Tax status: the tax rule of both carriers. Taxable: <tax rule>: live rates are taken without VAT and PrestaShop adds the shipping tax of the selected rule. None: live rates are taken including VAT.

ShipLogic API (live rates and lockers)

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)

Price source: where the price comes from.

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

Sender address (for live rates) (where The Courier Guy collects the parcels, in South Africa; 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 the South African province from the list.

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

Price table (your own prices in the shop 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 trash icon to remove 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 carriers in that case.

Conditions (both carriers)

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

Max weight (kg): hide the carriers 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 carriers 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 carriers are shown with a price of 0 and no request goes to ShipLogic for the rate.

Availability without shipping zones

Normally the carriers are offered in the shipping zones they are linked to in Shipping > Carriers.

Ignore shipping zones: offer the carrier of the delivery type below for the countries below, even where its zones do not contain them. The carrier is linked to every active zone, also to zones created later. When you switch the option off again, it gets back the zones it had before.

Delivery type without zones: Courier to the door or TCG locker (customer chooses a locker). Used only with Ignore shipping zones.

Countries: the destination countries for that mode. Leave empty to allow every country. Lockers are offered in South Africa only.

Advanced

South African provinces: PrestaShop has no South African provinces, but the live courier rate needs the province of the address. Add South African provinces adds the 9 provinces (EC, FS, GP, KZN, LP, MP, NC, NW, WC) as states of South Africa and shows the state field in South African addresses. Provinces that already exist are not added again. Until then, the courier gets the price table.

Debug log: writes debug messages to logs/vfd_tcgr_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. The API key and customer data 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 on, uninstalling the module deletes its settings and carriers. When off, uninstalling only switches the carriers off. Lockers saved on orders are always kept.

How it works at checkout

At the shipping step PrestaShop asks the module for the price of each carrier. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: cart weight and minimum order amount. If free shipping applies, the price is 0.

Courier to the door: the module 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 carrier 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 your shop units. The rand amount is converted to your default currency and then shown in the customer's cart currency.

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 carrier is hidden. API errors are never shown to the customer.

The carriers work on the Classic and the Hummingbird theme. If you edit a carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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 carrier (the cheapest service level) is shown, with no choice of service levels, insurance or extras at checkout.

Pickup points

When the customer chooses the locker carrier, a locker selector appears under it. It lists the lockers ShipLogic returns for the city of the delivery address, closest first. 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 shipping step shows Please choose a The Courier Guy locker.

The locker is checked again on the server against ShipLogic's list, also when the order is placed. Its name and provider are taken from ShipLogic, never from the browser. The choice is kept for the cart and is reset when the delivery address changes.

If ShipLogic cannot be reached, the selector says that lockers cannot be loaded and that the shop will contact the customer 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.

Orders

The chosen locker (name, ID and provider) is saved with the order. It is shown in the The Courier Guy block of the admin order page, on the order confirmation page and in the customer's order details, and in the order confirmation e-mail. The shop's "new order" e-mail (Mail alerts module) also shows the locker ID, or that no locker was chosen because ShipLogic was unavailable.

The Courier Guy tracking reference: book the parcel in your The Courier Guy portal and enter the reference as the tracking number of the shipment in the Shipping block of the order (Edit). The The Courier Guy block shows it. The customer sees it in the order details and gets the "in transit" e-mail from PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox The Courier Guy is the first block on Modules > Module Manager > VibeFox The Courier Guy > Configure, 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 shop. Below them are the line Product: presta-shipping-the-courier-guy and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, neither The Courier Guy carrier (courier to the door or TCG locker) is shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carriers are 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the module always removes the license key and license status. Reset of this module does not delete data, so the key and the status are kept.

Troubleshooting

The Courier Guy does not appear at checkout: check that the license is active and the carrier is switched on (Courier to the door or TCG locker). In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or that Ignore shipping zones is on and the country is allowed). Check the weight limits and Minimum order amount. Check that the table or Fallback cost has a price. The locker carrier appears only for South African addresses and with the API key. Products can also be limited to certain carriers in the product page.

Customers see no locker list: lockers need the API key, the TCG locker carrier 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 non-rand shops, the ZAR conversion rate. For courier delivery the customer's address needs a street, city, province and postal code: add the South African provinces in the Advanced section. 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 module 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 module page. This clears the cached rates and lockers.

The page says a The Courier Guy carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps your settings and the on/off status of the existing carriers.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox The Courier Guy and choose Uninstall. The license key and the license status are always removed. The cached rates and lockers and the last ShipLogic error are always removed. If Remove data on uninstall is on, the carriers are deleted (orders keep their history), and the settings, the log and the lockers of carts without an order are removed. If it is off, the carriers are only switched off and all settings are kept. Installing the module again gives the carriers back the status they had. Lockers saved on orders are never removed.

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