VibeFox CTT 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.
CTT e-commerce account (for live rates and CTT points only): live rates and delivery to a CTT point use the CTT e-commerce API. You need a CTT e-commerce account at enviosecommerce.ctt.pt (for CTT Expresso contract customers, or ask CTT for a proposal). In the key management page of that account, create a public and private key pair. The App ID (X-APPID) is issued by CTT for your integration: ask your CTT e-commerce contact. CTT also decides which API functions (cost estimate, CTT points) your App ID may use. Finally you need the Carrier ID of CTT in your account. The settings page lists the carriers of your account once the keys are saved. If you only use the price table and delivery to the address, you do not need API keys.
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_ctt-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_ctt.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_ctt-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 CTT 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 price table (at least a Portugal or * Default row), turn on Enable/Disable and/or Enable CTT point option and click Save. Optionally fill in the CTT API keys, the App ID and the Carrier ID and turn on Live rates (see Configuration).
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_ctt.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 CTT, 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 the first install both shipping options are off until you turn one on and save. If you install the extension again after an uninstall without removing data, the settings you kept are used again and the extension is enabled again if one of the options was on.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox CTT > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. The prices and conditions apply to both CTT options. Every save clears the cached CTT answers: the API token, the carriers, the prices and the CTT point lists. Only admin users with the modify permission for this extension can save the settings.
Warnings at the top of the page tell you about an empty price table, a missing price for Portugal, incomplete API keys while live rates or the CTT point option are on, a missing Carrier ID, a store currency other than EUR without an exchange rate, a failed connection to the CTT API, and a store without a weight class with the unit kg or a length class with the unit cm (product units are then converted by their unit name; check System > Localisation > Weight Classes and Length Classes). If a name is empty, invalid or longer than 64 characters, Min weight (kg) is greater than Max weight (kg), or Sort Order, the tax class or the geo zone is invalid, the page shows an error and nothing is saved. Other invalid values are reported as warnings and the rest is saved: an invalid number is not saved, an exchange rate of 0 or less is cleared, an invalid product size is reset to the default, an unknown destination or a duplicate row in the price table is removed, an invalid table price is left empty.
General
The extension offers up to two options at checkout: CTT delivery to the customer's address and delivery to a CTT point or parcel locker. The prices and conditions apply to both.
Enable/Disable: turns CTT delivery to the customer's address on or off.
Name: the shipping method name shown to the customer at checkout, for example "CTT Expresso". Default: CTT. Up to 64 characters.
Tax class: the tax class of the shipping cost. OpenCart adds that tax (for example IVA) on top of the prices. --- None --- means the prices are final. Used by both options.
Sort Order: the position of CTT among the shipping methods at checkout. A whole number.
Delivery to a CTT point or parcel locker
The second CTT option. The customer searches CTT points by postcode or city (the delivery address is searched automatically) and must choose one before continuing. It needs the CTT API keys and the Carrier ID. Without them it is an option without point selection.
Enable CTT point option: offers delivery to a CTT point or parcel locker. Default: off.
CTT point option name: the name of this option at checkout. Default: CTT point / parcel locker. Up to 64 characters.
CTT e-commerce API (live rates, CTT points) (optional; without keys the price table is used)
Public key: the public key from the key management page of your CTT e-commerce account.
Private key: the secret key used to sign every request (HMAC-SHA256). It is never sent to CTT or written to the log.
Both keys are never shown again after saving. The field description then says Saved - leave empty to keep it. Type a new value only to change it. Tick Remove the saved public and private key and save to delete both. When nothing is saved, the section shows No keys saved.
App ID (X-APPID): the application key issued by CTT, sent in the X-APPID header.
Carrier ID: the ID of the CTT carrier in your account, used for live rates and the CTT point search. After the keys and the App ID are saved, the carriers of your account are listed under the field (Carriers of your CTT account:), with the ones that support CTT points marked CTT points. Numbers only.
Live rates: ask CTT for the price (cost estimate) once the customer has entered the street, postcode and city. The price table is used while the address is incomplete and whenever CTT gives no price. CTT calls this price an estimate. Default: off.
Service ID: optional. When CTT returns several services, the one with this ServiceId is used. Leave it empty to use the cheapest one.
Exchange rate: CTT prices are in euro. If your store default currency is different, enter how many units of your store currency equal 1 unit of the CTT currency. Without it, live rates in another currency are not used and the price table applies.
Default product size (cm): length x width x height sent to CTT for products without dimensions. Default: 30x20x15. Products with dimensions use their own. Dimensions are converted to cm and weights to grams from the length and weight classes of the products.
Prices (the section title shows your store default currency)
Enter the prices of your CTT contract or of the public CTT price list at ctt.pt, in the store default currency, tax excluded. With live rates off this table sets the price. With live rates on it is the fallback.
Price table: one row per destination. Choose a country, Portugal - Azores, Portugal - Madeira or * Default (other destinations). Each row has a base Price and optional prices for the sizes 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). An empty (or 0) size price uses the base price. A row where both are empty hides the method. The Azores row is used for Portuguese postcodes 9500-9999, the Madeira row for 9000-9499. Without them the Portugal row applies. Click Add destination to add a row and the × button to remove one. Prices accept a decimal point or comma. The table is empty after install.
Calculation: how the table price is found.
A live CTT price is always for the whole shipment.
Conditions
Min weight (kg): the minimum cart weight for the CTT options to appear. 0 means no limit.
Max weight (kg): the CTT options are hidden above this cart weight. Default: 30 (CTT parcels go up to 30 kg). 0 means no limit. Min weight (kg) cannot be greater than Max weight (kg).
Minimum order amount: show the CTT options only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show them.
Free shipping
Free shipping: turn on free CTT delivery from the amount below.
Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which the CTT options cost 0. It applies only to destinations that have a price. Used only when Free shipping is on.
Availability
Normally the CTT options are offered in the geo zone selected below. All Zones means everywhere. With Ignore shipping zones the geo zone is not checked and Countries decides.
Geo Zone: the geo zone of the shipping address. Geo zones are managed in System > Localisation > Geo Zones.
Ignore shipping zones: do not check the geo zone; offer CTT in the countries below.
Countries: the destination countries for that mode. Default: Portugal. Leave it empty to allow all countries. Used only with Ignore shipping zones.
Advanced
Debug log: logs the price calculation and the CTT API calls to storage/logs/vfd_ctt_debug.log.php (on OpenCart 4 system/storage/logs/vfd_ctt_debug.log.php). The file cannot be read from the web. CTT API errors are always logged, even when this is off. Keys, tokens and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_ctt_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 log and the CTT points of unfinished checkouts. When off (default), the settings are kept for a re-install. Orders, including the chosen CTT point, are never changed.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The public and private key 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 keys are kept.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the CTT price. With Ignore shipping zones CTT is offered only for a country in Countries (empty = all countries); otherwise, if a Geo Zone is set, only for addresses inside it. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension checks the cart weight and the minimum order amount. With Live rates on and a complete address, it sends CTT the delivery address and, for each cart line, the quantity, the weight in grams and the dimensions in cm, and uses the returned price. Otherwise, or when CTT gives no price (API error, timeout, no coverage, a function not enabled for your App ID), the price comes from the table. If free shipping applies, the price is 0. Both options get the same price. The price is calculated in your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.
A CTT price is cached for 1 hour, so the same cart does not trigger a new request. A failed request is remembered for 5 minutes, so the checkout does not wait for CTT on every refresh. The API token, the carrier list and the CTT point lists are cached too, at most for the OpenCart cache lifetime (1 hour by default). API errors never reach the customer: the table price is used, or the method is hidden if the destination has no price.
With API keys filled in, the extension sends the delivery address, product weights and dimensions and your store URL to CTT to get a price or the nearest CTT points.
The extension does not create shipments, print labels, request pickups, provide tracking numbers or show a map of CTT points. There is one price table and one set of API settings for both options.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks a CTT option in the window Shipping method options. The prices are the same as on OpenCart 3.
Pickup points
When the customer selects the CTT point option at the delivery method step, a search field and a list appear under it. The postcode of the delivery address is filled in and searched automatically. The customer can search other CTT points by postcode or city (button Search) and chooses one from the list. The choice is saved at once. Only a point from the CTT list for that search is accepted.
A point must be chosen before the customer can continue. When the customer clicks Continue, the extension checks the point on the server. Without a point the customer sees Please select a CTT point., with a point that is not in the CTT list The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. If CTT cannot be reached, the customer sees CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
The point selection is active only when the public key, private key, App ID and Carrier ID are filled in. It is made for the default OpenCart theme and its checkout; other themes may need changes.
On OpenCart 4 the search field and the list appear in the window Shipping method options, under the CTT point option. The Continue button of the window does not go on without a valid point, with the same messages. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the CTT point of the order is updated with it.
The chosen point is added to the shipping method of the order, for example CTT point / parcel locker: .... So the customer sees it in the order history of their account and in the order e-mails, and it is printed on the invoice and shown in Sales > Orders. The OpenCart order success page does not show the shipping method.
On the admin order page, the CTT point panel above the history shows the point name and ID. To change it, enter a postcode or city under Change CTT point, click Search, choose a point and click Save. The page shows CTT point updated., the shipping method text of the order is updated, and an order history entry CTT point changed to: ... is added without notifying the customer. Changing the point needs the modify permission for orders (sale/order) and the API settings. The panel is shown for CTT orders also while the extension is disabled.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox CTT is the first block on Extensions > Extensions > Shipping > VibeFox CTT > 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-ctt 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, CTT 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
CTT does not appear at checkout: check that the license is active and Enable/Disable (or Enable CTT point option) is on. Check Geo Zone, or Ignore shipping zones and Countries. Check that the destination has a row in the price table (or a * Default row), the cart weight is within Min weight and Max weight, the Minimum order amount is reached and the products have Requires Shipping set to Yes.
The customer cannot choose a CTT point: the selector appears only under the CTT point option, and only when the public key, private key, App ID and Carrier ID are filled in. Check the warnings at the top of the settings page, turn on Debug log and look at the Log field on the extension page.
Live rates do not appear: the price table is used until the customer has entered the street, postcode and city. Check the warnings and the log. An answer "405" means the function is not enabled for your App ID: ask CTT. In a store not in euro, fill in Exchange rate.
The connection to the CTT API failed: the warning at the top of the settings page shows the error. Check the keys and the App ID. The extension retries automatically after a few minutes.
Prices with or without VAT: with a Tax class selected OpenCart adds that tax on top of the price. With --- None --- the price is final.
Prices look outdated after a change: click Save on the extension page. This clears the cached CTT answers.
The page says "Warning: You do not have permission to modify VibeFox CTT!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_ctt (OpenCart 3) or extension/vfd_ctt/shipping/vfd_ctt (OpenCart 4) in System > Users > User Groups.
For developers: the CTT API address can be replaced with the setting vfd_ctt_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 CTT. The license key and license status of this extension are always removed. OpenCart always resets the extension status, Sort Order, Tax class and Geo Zone. The cached CTT answers and the API token are always removed. If Remove data on uninstall is on, the settings, the log and the CTT points of 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. CTT points saved in 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 CTT in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
CTT is a trademark of its respective owner. This extension is not affiliated with or endorsed by CTT.