VibeFox Canada Post for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Canada Post Developer Program (for live rates only): live rates use the Canada Post Rating API. Join the Canada Post Developer Program on the Canada Post website and copy your API key and your customer number. The API key has the form username:password, and Canada Post gives separate keys for the development (sandbox) and production environments. You also need the Canadian postal code you ship from. If you only use fixed prices, you do not need API keys.
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 Canada Post 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. For live rates, enter the API username and password, your customer number and the ship-from postal code. If your shop default currency is not CAD, enter the CAD rate. Fill in Country prices if you want fixed prices or a fallback (see Configuration). Click Save.
On install the module creates the Canada Post carrier with the transit time text Canada Post parcel delivery. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, transit 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 Canada Post > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Canada Post rates. Saving needs the configure permission for the module.
When a value is wrong, the page shows an error and nothing is saved: a number field or a price in Country prices that is not a number of 0 or more (for example -1 or 12abc), a CAD rate of 0, Min cart weight (kg) greater than Max cart weight (kg), or a Method title longer than 64 characters. If your shop weight or dimension unit is one the module does not know, the page warns that weights are read as kg (dimensions as cm). Set kg, g, lb or oz (cm, mm, m or in) in International > Localization, section Local units.
After saving, the page shows a warning when the settings cannot work as intended: only one of the API username and password is filled in, the ship-from postal code is not a Canadian postal code (format A1A 1A1), the CAD rate is missing for a shop in another currency, or there are neither API credentials nor fixed prices. The warning also says what happens meanwhile: the fixed country prices are used, or the carrier is hidden at checkout when the Country prices table is empty.
General
Enable Canada Post: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Method title: the carrier name shown to the customer at checkout. Default: Canada Post, also when the field is left empty. Up to 64 characters, without characters that PrestaShop does not allow in carrier names.
Tax: the tax rule PrestaShop adds on top of the shipping cost, or No tax (not taxable).
Canada Post API (live rates)
With the API username and password filled in, the price comes from the Canada Post Rating API. If the API gives no rate (API down, wrong postal code, service not available), the fixed price from Country prices is used, or the carrier is hidden when there is none. The section links to the Canada Post Developer Program, where you find the API keys and your customer number. Error details go to the log, never to the customer.
API username: the part of the API key before the colon. Use the development key with Sandbox and the production key on a live shop.
API password: the part of the API key after the colon. After saving, the field stays empty and says A password is saved. Leave empty to keep it; clear the username and save to remove both. Type a new value only to change it. The password is saved exactly as typed and is never written to the log.
Customer number: with a customer number Canada Post returns the commercial (discounted) rates of your account. Leave it empty for retail (counter) rates. Spaces are removed.
Contract number: optional, for contract customers. It is used only together with the customer number.
Sandbox: uses the Canada Post development environment, for testing with the development API key. The prices are test data. Turn it off on a live shop.
Ship-from postal code: the Canadian postal code the parcels are sent from, for example K1A 0B1. Live rates need it.
Service in Canada: the service for Canadian addresses: Cheapest available, Regular Parcel (DOM.RP, default), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) or Priority (DOM.PC).
Service to the USA: Cheapest available (default), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) or Priority Worldwide parcel USA (USA.PW.PARCEL).
International service: Cheapest available (default), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) or Priority Worldwide parcel International (INT.PW.PARCEL).
If the chosen service is not offered for the address or parcel, the cheapest available one is used.
Use Canada Post prices without GST/HST/PST: for Canadian addresses the Canada Post price includes these taxes. Turn this on when PrestaShop adds tax on shipping itself (Tax above), so the tax is not charged twice.
CAD to … rate: the field name shows your shop default currency, for example CAD to USD rate. Canada Post prices are in CAD. If your default currency is not CAD, enter how many units of your currency one CAD is worth, for example 0.68. Without it live rates are not used. If your default currency is CAD, leave it empty. The rate must be greater than 0. Both a point and a comma are accepted as the decimal separator.
Default product weight (kg): sent to Canada Post for each product that has no weight. Default: 0.5. Product weights (in your shop weight unit) and dimensions are converted, and the cart is rated as one parcel.
Fixed prices (used without API credentials, and as the fallback when the API gives no rate)
Country prices: a table of countries with a Base price and prices by cart weight in your shop default currency, tax excluded: XS up to 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL over 5 kg. An empty or zero size price uses the Base price. Click Add country to add a row and the cross to remove one. The row * Default (all other countries) sets prices for all countries without their own row. A country without a row (and without *) gets no fixed price. A base price of 0 means free shipping for that country. A row without any price is not saved.
Fixed price per: Order charges the price once. Item (price x quantity) multiplies it by the number of items in the cart. This applies to fixed prices only. Live rates are always calculated for the whole parcel.
Conditions
Min cart weight (kg): hide the carrier below this cart weight. 0 means no limit.
Max cart weight (kg): hide the carrier above this cart weight. Default: 25, also when the field is empty. 0 means no limit. Canada Post parcels can weigh up to 30 kg. It cannot be lower than Min cart weight (kg).
Minimum order amount: show the carrier only when the cart subtotal (products after discounts, tax excluded) reaches this amount. Leave it empty to always show it.
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal from which shipping is free. No API request is made in that case. Used only when Free shipping is on.
Availability without shipping zones
Normally the carrier is shown in the zones it is assigned to in Shipping > Carriers.
Ignore shipping zones: offer the carrier for the countries below, whatever zone matches. On save the carrier is added to all zones, and zones you create later are added too. When you turn the option off and save, the zones the module added are removed again, and the carrier keeps its own zones.
Countries: the destination countries for that mode. Hold Ctrl (Cmd) to select several. Leave it empty to allow all active countries. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs rate calculations to var/logs/vfd_canada_post.log.php. The file cannot be opened from the web, and it is rotated at 5 MB. API errors are always logged, even when this option is off. API keys, customer numbers and customer postal codes are not logged.
Remove data on uninstall: when on, uninstalling the module deletes the settings, the saved order services, cached rates and the log. The carrier is always removed from the checkout on uninstall. Orders are never touched.
Log: the panel under the settings shows the file name and the latest 50 entries. Click Clear log to delete it.
How it works at checkout
At the shipping step PrestaShop asks the module for the Canada Post price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to Canada Post.
With API credentials, the module sends Canada Post the ship-from postal code, the destination, the parcel weight and, when every product has dimensions, the estimated parcel size. For Canada the destination is the postal code, for the USA the ZIP code, for all other countries only the country. A live rate is requested only when a Canadian or US address has a valid postal or ZIP code. Canada Post returns all services for the parcel. The module picks the chosen service of the destination group or the cheapest one, removes Canadian sales taxes if Use Canada Post prices without GST/HST/PST is on, and converts the CAD price with your rate. The price is calculated in your default currency and then shown in the customer's cart currency.
Each answer is cached for 1 hour, so the same cart and address do not trigger a new request. A failed request is cached for 10 minutes, so a Canada Post outage does not slow down every checkout refresh. The API timeout is 10 seconds. Parcels over 30 kg are not sent to the API.
If the API gives no rate, the fixed price is used, or the carrier is hidden when there is no fixed price. The customer never sees API error details; they go to the log.
If you edit the carrier in Shipping > Carriers, PrestaShop saves it as a new carrier version. The module follows the new version automatically.
The module calculates rates only. It does not create shipments, print labels, create manifests or returns, or track parcels. Customers cannot choose a post office or pickup point. It shows one Canada Post rate, without delivery dates, insurance or signature options. The cart is always rated as one parcel, and currency rates are not updated automatically.
Orders
When an order is placed with the Canada Post carrier, the module saves how its price was calculated. On the admin order page (Orders > Orders, open an order) a Canada Post block shows:
Canada Post service: the service name and code of a live rate, for example Regular Parcel (DOM.RP).
Price source: Live rate (Canada Post Rating API), Fixed price or Free shipping.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Canada Post is the first block on Modules > Module Manager > VibeFox Canada Post > 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-canada-post 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, the Canada Post carrier is not 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 carrier 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 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 or resetting the module always removes the license key and license status.
Troubleshooting
Canada Post does not appear at checkout: check that the license is active and Enable Canada Post is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or Ignore shipping zones is on and the country is allowed). Check the weight limits and Minimum order amount. There must be a rate: with API credentials the address needs a valid postal code (Canada) or ZIP code (USA); otherwise a fixed price for the country or * must exist. Products can also be limited to certain carriers in the product page.
Live rates do not appear: turn on Debug log, reload the checkout and look at the Log panel on the module page. It shows the reason: missing API username or password, an invalid ship-from or destination postal code, a missing CAD rate, a parcel over 30 kg, or the Canada Post error message. Meanwhile customers get the fixed price if there is one.
The rate is different from the Canada Post website: with a customer number you get the commercial (discounted) rates of your account; without it, retail (counter) rates. For Canadian addresses the Canada Post price includes GST/HST/PST. Prices are converted with your CAD rate.
Tax is charged twice on shipping: turn on Use Canada Post prices without GST/HST/PST, or set Tax to No tax.
Test prices on a live shop: turn off Sandbox and use the production API key.
Rates look outdated after a change: click Save on the module page. This clears the cached Canada Post rates.
The page says the Canada Post carrier is missing: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
You do not have permission to configure this module: your employee profile can open the module page but not save it. Ask an administrator to give your profile the configure permission for the module.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Canada Post and choose Uninstall. The license key and license status are always removed. The carrier is always removed from the checkout (orders keep their carrier and history). If Remove data on uninstall is on, the settings, the saved order services, cached rates and the log are deleted. If it is off, only the cached rates are removed and all settings are kept. Installing the module again (or Reset) restores the previous carrier with its previous status: a carrier you had disabled stays disabled.
Canada Post is a trademark of its respective owner. This module is not affiliated with or endorsed by Canada Post.