VibeFox Canada Post 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.
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
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_canada_post-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_canada_post.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_canada_post-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 the package into the root folder of your store.
2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Canada Post 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. For live rates, enter the API username and password, your customer number and the ship-from postal code. If your store default currency is not CAD, enter the CAD rate. Fill in Country prices if you want fixed prices or a fallback (see Configuration). Turn on Enable Canada Post and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_canada_post.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 type Shipping. Find VibeFox Canada Post, 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 install the method is off until you turn on Enable Canada Post and save. If you install the extension again after an uninstall, the settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Canada Post > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Canada Post rates. Only admin users with the modify permission for this extension can save the settings.
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), a Method title longer than 64 characters or with the characters < > ; = # { }, a Sort order that is not a whole number, or an unknown tax class or geo zone. If the store has no weight class with the unit "kg" or no length class with the unit "cm", the page warns that weights and dimensions are converted by the unit name of their class (kg, g, lb, oz; cm, mm, m, in), and other units are read as kg or cm.
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 store 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 method is hidden at checkout when the Country prices table is empty.
General
The settings apply to every geo zone. The price always comes from this extension: a live Canada Post rate or the fixed country prices.
Enable Canada Post: shows or hides Canada Post at checkout. Default: off.
Method title: the shipping method name shown to the customer at checkout. Default: Canada Post, also when the field is left empty. At most 64 characters.
Tax class: the tax class OpenCart adds on top of the shipping cost, or No tax (not taxable).
Sort order: the position of Canada Post among the shipping methods at checkout.
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 method 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 store.
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 API 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 store. Default: off.
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 OpenCart adds tax on shipping itself (Tax class above), so the tax is not charged twice.
CAD to … rate: the field name shows your store 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.
Default product weight (kg): sent to Canada Post for each product that has no weight. Default: 0.5. Product weights and dimensions are converted from the weight and length classes of the products, and the cart is rated as one parcel (up to 30 kg).
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 store 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. The row * 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.
Fixed price per: Order (default) charges the price once. Item (price × 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 method below this cart weight. 0 means no limit (default).
Max cart weight (kg): hide the method 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.
Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, 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 subtotal of the products that need shipping (after the coupon, tax excluded) from which shipping is free. No API request is made in that case. Used only when Free shipping is on.
Geo zone: offer Canada Post only for addresses in this geo zone. All zones (default) means everywhere. Not used when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.
Availability without shipping zones
Normally the method is offered in the geo zone selected in Conditions.
Ignore shipping zones: offer the method for the countries below, whatever the geo zone.
Countries: the destination countries for that mode. Leave it empty to allow all enabled countries of the store. Used only when Ignore shipping zones is on.
Advanced
Debug log: writes rate calculations to storage/logs/vfd_canada_post.log.php. The file cannot be read from the web. When it reaches 5 MB, it is moved to vfd_canada_post.old.log.php and a new log is started. API errors are always logged, even when this option is off. API keys, customer numbers and customer postal codes are not 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 extension deletes the settings, the saved order services, cached rates and the log. When off (default), they are kept for a re-install. Orders are never touched.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The API password is 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 API password is kept while the API username stays filled in.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the Canada Post price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Canada Post is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the price is 0 and no request goes to Canada Post.
With API credentials, the extension 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 extension 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, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.
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 method is hidden when there is no fixed price. The customer never sees API error details; they go to the log.
The extension 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.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Canada Post in the window Shipping method options, for example Canada Post - $12.50. The method works the same way as on OpenCart 3.
Orders
When an order is placed with Canada Post, the extension saves how its price was calculated. On the admin order page (Sales > 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.
On OpenCart 4 the block is shown above History. The checkout keeps one order: when the customer confirms the order again, the saved service and price source are replaced, and they are removed if the customer chose another shipping method.
The service is not added to the order e-mails or to the customer's order page; they show the method title and the shipping cost like any other OpenCart shipping method.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Canada Post is the first block on Extensions > Extensions > Shipping > VibeFox Canada Post > 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-canada-post 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, Canada Post 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
Canada Post does not appear at checkout: check that the license is active and Enable Canada Post is on. Check Geo zone, or that Ignore shipping zones is on and the country is allowed. Check the weight limits and Minimum order amount, and that the products have Requires Shipping set to Yes. 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.
Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension 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 class to No tax.
Test prices on a live store: turn off Sandbox and use the production API key.
Rates look outdated after a change: click Save on the extension page. This clears the cached Canada Post rates.
The page says "Warning: You do not have permission to modify VibeFox Canada Post!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_canada_post (OpenCart 3) or extension/vfd_canada_post/shipping/vfd_canada_post (OpenCart 4) in System > Users > User Groups.
For developers: the Canada Post API address can be replaced with the setting vfd_cp_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 Canada Post. The license key and license status of this extension are always removed. OpenCart always resets Enable Canada Post, Sort order, Tax class and Geo zone. The cached rates are always removed. If Remove data on uninstall is on, the settings, the saved order services and the log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. 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 Canada Post in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
Canada Post is a trademark of its respective owner. This extension is not affiliated with or endorsed by Canada Post.