VibeFox CTT for WooCommerce — Help
Requirements
WordPress: 5.8 or later.
WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.
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 home delivery, you do not need API keys.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_ctt folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox CTT, or click Settings under the plugin name on the Plugins page.
4. Enter your VibeFox license key in the license block at the top of the page and click Activate.
5. Fill in the price table (at least a Portugal or * Default row). Optionally fill in the CTT API keys and the Carrier ID and turn on Live rates (see Configuration).
6. In WooCommerce > Settings > Shipping > Shipping zones, open or create a zone for Portugal and add VibeFox CTT. In the method settings choose the title and the delivery type. Or turn on Ignore shipping zones and choose countries.
Configuration
Prices, API keys and conditions are on one page: WooCommerce > Settings > Shipping > VibeFox CTT. They apply to every shipping zone. When you add the method to a zone, the zone window has two fields:
Title (zone): the name of this option at checkout in this zone. Leave it empty to use the global Name.
Delivery: To the customer's address (default) or To a CTT point or parcel locker chosen at checkout. A CTT point needs the CTT API keys and the Carrier ID in the global settings. Add the method twice to a zone to offer home delivery and CTT point delivery side by side.
Warnings above the settings tell you about a missing price for Portugal, incomplete API keys, a missing Carrier ID, a store currency without an exchange rate and a failed connection to the CTT API. Every time you save the settings, the cached CTT answers are cleared.
General
Enable/Disable: turns the method on or off in all zones at once.
Name: the shipping method name shown at checkout, for example "CTT Expresso". Default: CTT. A zone Title overrides it.
Tax status: Taxable adds the WooCommerce shipping tax (for example IVA) on top of the price, None means the price is final.
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.
App ID (X-APPID): the application key issued by CTT for your integration.
Carrier ID: the ID of the CTT carrier in your account, used for live rates and the CTT point search. After the keys are saved, the carriers of your account are listed under the field, with the ones that support CTT points marked.
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 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 your store units.
Prices (the section title shows your store currency)
Enter the prices of your CTT contract or of the public CTT price list, in the store currency. 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 (PT-AC), Portugal - Madeira (PT-MA) 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 (including Porto Santo) for 9000-9499. Without them the Portugal row applies. Click + Add destination to add a row and the cross to remove one. Prices accept a decimal point or comma. Invalid rows are reported when you save.
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 method to appear. 0 means no limit.
Max weight (kg): the method is hidden above this cart weight. Default: 30 (CTT parcels go up to 30 kg). 0 means no limit.
Minimum order amount: show the method only when the cart subtotal (after discounts, before tax) reaches this amount. Leave empty to always show it.
Excluded shipping classes: hide the method when any cart item belongs to one of these WooCommerce shipping classes.
Free shipping
Free shipping: turn on free CTT delivery from the amount below.
Free shipping from: the cart subtotal (after discounts, before tax) from which this method costs 0. It applies only where the method has a price. Used only when Free shipping is on.
Availability without shipping zones
Ignore shipping zones: offer the method in the countries below when the customer's zone does not contain it.
Countries: the destination countries for that mode. Default: Portugal. Leave empty to use all countries you ship to. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs the price calculation and the CTT API calls in WooCommerce > Status > Logs, source vfd-ctt. CTT API errors are always logged, even when this is off. Keys, tokens and customer addresses are never logged.
Remove data on uninstall: when on, deleting the plugin removes its settings and zone methods. Deactivating the plugin never deletes data. Orders are never changed.
How it works at checkout
When the customer enters a delivery address, WooCommerce asks the plugin for a price. The plugin first checks the cart weight, the minimum order amount and the excluded shipping classes. 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 shows 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.
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 timeout is 12 seconds.
The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).
With API keys filled in, the plugin sends the delivery address, product weights and dimensions and your shop URL to CTT to get a price or the nearest CTT points.
The plugin 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 the whole store. Zones differ by title and delivery type.
Pickup points
For a zone method with Delivery set to a CTT point, a search field and a list appear under the method at checkout. The delivery address is searched automatically. The customer can search other CTT points by postcode or city and must choose one before placing the order. This is checked on the server too. The CTT point lists are cached for 6 hours. If CTT cannot be reached, the customer sees a message and can try again later or choose another shipping method.
The chosen point is saved in the order. It is shown in the order admin under the shipping address, on the order received page, in My account > Orders and in the order e-mails (HTML and plain text) as CTT point.
In the order admin, click Change next to the CTT point, search by postcode or city and choose another point. The change is saved at once and adds an order note.
License key
The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox CTT. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.
One key works on one domain. Removing the key from a site 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. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.
When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.
Troubleshooting
CTT does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). 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 no product belongs to an excluded shipping class.
The customer cannot choose a CTT point: the selector appears only for a zone method with Delivery set to a CTT point, and only when the public key, private key, App ID and Carrier ID are filled in. Turn on Debug log and check WooCommerce > Status > Logs.
Live rates do not appear: the price table is used until the customer has entered the street, postcode and city. Check the warnings above the settings 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 above the settings shows the error. Check the keys and the App ID. The plugin retries automatically after a few minutes.
Prices with or without VAT: with Tax status Taxable WooCommerce adds the shipping tax on top of the price. With None the price is final.
The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.
Uninstall
Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, as are the cached CTT answers and the API token. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Orders, including the chosen CTT point, are never changed, and existing orders keep their shipping lines.
CTT is a trademark of its respective owner. This plugin is not affiliated with or endorsed by CTT.