VibeFox The Courier Guy for Adobe Commerce — सहायता
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.
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 allowed country of the store (Stores > Configuration > General > General > Country Options > Allow Countries).
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-the-courier-guy-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/TheCourierGuyShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_TheCourierGuyShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox The Courier Guy. 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. Choose 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 the base currency of your store is not ZAR, the ZAR conversion rate. Fill in the price table and/or a fallback cost. Set Enable to Yes and click Save Config.
The module adds the The Courier Guy shipping method to Magento with two options. Customers see them as The Courier Guy - Courier delivery and The Courier Guy - TCG locker (method title and option name). The module is off after installation (Enable = No). It keeps the locker choices of carts and the locker data of orders in its own database table.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox The Courier Guy, in the standard Magento configuration form. Like other Magento settings, most of them can be changed for a website with the Scope switcher at the top of the page; Method title, Courier option name and Locker option 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 rates, lockers and the last ShipLogic error. Amounts and weights 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, Courier option name or Locker option name, longer than 64 bytes or with one of the characters < > ; = # { }; a Sort order that is not a whole number. Other wrong values do not stop the save. A number field that does not contain a non-negative number (or a ZAR conversion rate of 0), or an Account ID that is not a number, keeps its previous value, and the warning The Courier Guy: invalid <field>; its previous value was retained. names the field. If Minimum weight (kg) is greater than Maximum weight (kg), both limits keep their previous values. A table price that is not a number is cleared, and a warning lists it.
While Enable is Yes, warnings after saving remind you of settings that stop live rates or lockers: South Africa is not allowed by the store; no ShipLogic API key (only the price table is used, locker delivery is unavailable); no ZAR conversion rate for live rates in the base currency; an incomplete sender address; no price table or fallback cost; a weight unit the module does not know (product weights are then read as kg). The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable: shows or hides The Courier Guy at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: The Courier Guy. Required, at most 64 bytes.
Courier to the door: turns the courier option on or off. Default: Yes.
Courier option name: shown after the method title, as "Method title - Courier option name". Default: Courier delivery. Required, at most 64 bytes.
TCG locker: turns the locker option on or off. Default: Yes. The customer chooses a locker at checkout. It is offered only for South African addresses and only with the ShipLogic API key.
Locker option name: shown after the method title for the locker option. Default: TCG locker. Required, at most 64 bytes.
There is no tax field: live rates are always taken without VAT. Whether Magento adds tax on shipping is set in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
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. 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 and click Save Config. Only the price table is used then.
Account ID: optional. The numeric ShipLogic account ID, only if your key has access to several accounts.
Price source: where the price comes from.
ZAR conversion rate: 1 ZAR in the base currency. ShipLogic quotes in South African rand (ZAR). If the base currency of your store is not ZAR, enter how much 1 ZAR is in that currency, for example 0.05. Without it, live rates are not used and the price table applies. If your base currency is ZAR, leave it empty. The rate is not updated automatically.
Sender address (where The Courier Guy collects the parcels, in South Africa; street, city, province and postal code are needed for live rates)
Company: your company name.
Street address: for example 12 My Road.
Local area / suburb: the suburb of the sender address.
City: the city of the sender address.
Province: choose the South African province from the list.
Postal code: the postal code of the sender address.
Price table (your own prices in the base currency of your store, tax excluded: used with Price table only, outside South Africa and whenever no live rate is available)
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 country to add a row and Delete to remove one. A tier price above 0 replaces the Price column for that weight; an empty or 0 tier uses the Price column. A price of 0 means free shipping. The row * All other countries applies to countries without their own row and to a country row without any price.
Fallback cost: used when there is neither a live rate nor a table price. Leave it empty to hide the method in that case.
Conditions (both options)
Minimum weight (kg): hide the method below this cart weight. 0 means no limit.
Maximum weight (kg): hide the method above this cart weight. Default: 30. Empty restores 30 kg. 0 removes the limit.
Minimum order amount: show the method only from this cart subtotal (products that need shipping, tax excluded, after discounts, in the base currency). Leave it empty to always show it.
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.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).
Advanced
Ship to Applicable Countries: All Allowed Countries offers The Courier Guy for every country your store allows, Specific Countries only for the countries below. It applies to both options.
Ship to Specific Countries: the destination countries for Specific Countries. Live rates and lockers are for South Africa only; other countries use the price table.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Debug log: writes debug messages to var/log/vfd_tcgr_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. API warnings and errors are always logged, even when this option is off. The API key and customer address data are never logged.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes its settings, the log and the lockers of carts without an order (see Uninstall). The license key and the cached rates and lockers are always removed. Lockers saved on orders are never deleted.
Last ShipLogic error: shown while the method is enabled: the date and the message of the last failed ShipLogic request, for example a refused key. It is cleared by the next successful request of the same kind and by Save Config.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
How it works at checkout
At the shipping step Magento asks the module for the price of each option. 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 countries, the cart weight and Minimum order amount. If Free shipping from applies, the price is 0. A Magento cart price rule with free shipping also makes the price 0 (the weight and amount conditions still apply).
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 (State/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 with the total cart weight. Magento products have no standard dimensions, so each product counts as a 10 cm cube. The rand amount is converted to your base currency with the ZAR conversion rate; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.
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 module works with the standard Magento checkout (Luma). It 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.
Pickup points
When the customer chooses TCG locker for a South African address, the block Select a TCG locker appears at the shipping step. It lists the lockers ShipLogic returns for the city of the delivery address (or its postal code), closest first. The customer can type another city, suburb or postal code in City, suburb or postal code and click Search lockers, then chooses a locker in the list. A locker must be chosen before the customer can continue: otherwise the shipping step shows Please select a TCG locker. If the search finds nothing, the block says No TCG lockers found. Try another city or postal code.
The locker is checked again on the server against ShipLogic's list when the customer clicks Next and 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 country or the city of the delivery address changes. If the payment is cancelled at the payment page and the cart comes back, the customer can choose a locker again; an order placed before keeps its own locker.
If ShipLogic cannot be reached, the block says Lockers cannot be loaded. You may continue; the store will confirm the locker. The order can then be placed without a locker and is flagged Locker not chosen: ShipLogic was unavailable at checkout. A locker that was chosen earlier but could not be checked again is kept and flagged Locker not verified: ShipLogic was unavailable at checkout.
Orders and tracking
The chosen locker is added to the shipping description of the order ("The Courier Guy - TCG locker: <locker name>"), so it appears wherever Magento shows the shipping method, also in the order e-mails. The module also saves the locker (name, ID and provider) and the ShipLogic service code with the order.
On the admin order page (Sales > Orders > View, Information tab) and in the customer's order view (in the account, or on the Orders and Returns page for guests) the The Courier Guy block shows the locker, the flags above, ShipLogic service: and Tracking reference:. The block also works for older orders and when the module is switched off.
Book the parcel in your The Courier Guy portal, then enter the reference in Magento as the tracking number of the shipment: click Ship on the order page, under Tracking Information click Add Tracking Number, choose the carrier The Courier Guy and enter the reference as the Number. For an existing shipment use Add Tracking Number on the shipment page. The customer sees the number in the order and in the shipment e-mail, if you send it. The tracking window shows Tracking reference recorded by the store.: the module does not fetch tracking statuses.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox The Courier Guy is the first row of the VibeFox The Courier Guy 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-the-courier-guy 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, neither The Courier Guy option (courier to the door or TCG locker) is shown to customers at checkout, no rate is calculated and lockers are not listed. 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
The Courier Guy does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that Courier to the door or TCG locker is Yes. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Without a live rate, the price table or Fallback cost needs a price. 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 = Yes and a South African delivery address with a city or postal code. The Last ShipLogic error field shows the last failed request, if any, for example a refused key.
The price is always the table price: check the warnings after Save Config. A live rate needs the API key, Price source = Live ShipLogic rates, the complete sender address and, if your base currency is not ZAR, the ZAR conversion rate. For courier delivery the customer's address needs a street, city, province 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 in the Advanced section.
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 Config on the Delivery Methods page. This clears the cached rates and lockers.
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 saved lockers stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_TheCourierGuyShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_TheCourierGuyShipping to remove the data, then bin/magento module:disable Vibefox_TheCourierGuyShipping, delete the folder app/code/Vibefox/TheCourierGuyShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached rates and lockers are always removed. If Remove data on uninstall is Yes, the settings, the log and the lockers of carts without an order are removed too. If it is No, the settings and the log are kept for a re-install. The lockers saved on orders, the shipping descriptions and the tracking numbers of shipments stay with the orders. Lockers of carts that never became an order are also removed automatically after 30 days.
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.