VibeFox Canada Post 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, DOM, JSON and libxml extensions.

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 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-canada-post-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/CanadaPostShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CanadaPostShipping 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 Canada Post. 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. For live rates, enter the API username and password, your customer number and the ship-from postal code. If the base currency of your store is not CAD, enter the CAD conversion rate. Fill in Country prices if you want fixed prices or a fallback (see Configuration). Set Enable Canada Post to Yes and click Save Config.

The module adds the Canada Post shipping method to Magento. Customers see it as Canada Post - Parcel delivery (method title and method name). It is off after installation (Enable Canada Post = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Canada Post, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method 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 Canada Post rates. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: a Method title longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; 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 conversion rate of 0; a Min cart weight (kg) greater than the Max cart weight (kg) (an empty maximum means 25 kg).

While Enable Canada Post is Yes, warnings after saving remind you of settings that 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 conversion rate is missing when the base currency is not CAD, 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. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable Canada Post: shows or hides Canada Post at checkout. Default: No.

Method title: the shipping method name shown to the customer in the cart and at checkout (the carrier title in Magento). Default: Canada Post, also when the field is left empty. At most 64 characters.

Method name: shown after the method title, as "Method title - Method name". Default: Parcel delivery. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

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 names 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. Clear it and click Save Config to remove both the username and the saved password.

API password: the part of the API key after the colon. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete the saved password, clear the field and click Save Config; live rates then stop. The password is saved exactly as typed (surrounding spaces removed) 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: No.

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. Set it to Yes when Magento adds tax on shipping itself (a tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping), so the tax is not charged twice. Default: No.

CAD conversion rate: Canada Post prices are in CAD. If the base currency of the website is not CAD, enter how many units of the base currency one CAD is worth, for example 0.68. Without it live rates are not used, the fixed prices apply. If your base 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 are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs), and the cart is rated as one parcel of up to 30 kg. Magento products have no standard dimensions, so only the weight is sent and the parcel size is not calculated.

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 the base currency of your store, 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 Delete to remove one. 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. A row without any price is not saved.

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.

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 discounts, tax excluded, in the base currency) reaches this amount. Leave it empty to always show it.

Free shipping: set it to Yes for free delivery from the amount below. Default: No.

Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) from which shipping is free. No API request is made in that case. Used only when Free shipping is Yes.

Ship to Applicable Countries: All Allowed Countries offers Canada Post for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Advanced

Debug log: writes rate calculations to var/log/vfd_cp_debug.log.php in the Magento folder. The file cannot be opened from the web, and it is rotated at 5 MB. API errors are always logged, even when this 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 Yes, uninstalling the module with its data deletes the Canada Post settings and the log (see Uninstall). The license key and the cached rates are always removed. The Canada Post services saved with orders are order history and are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the Canada Post price. 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 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 and the parcel weight. 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 Yes, and converts the CAD price with your rate. The price is calculated in your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

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. A Magento cart price rule with free shipping makes the price 0.

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 Canada Post, the module saves how its price was calculated. On the admin order page (Sales > Orders > View, Information tab) the 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.

The block also works for older orders and when the module is switched off. The customer does not see the service.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Canada Post is the first row of the VibeFox Canada Post 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-canada-post 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, the Canada Post method is not shown to customers at checkout and no rate is calculated. 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

Canada Post does not appear at checkout: check that the license is active and Enable Canada Post is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, 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.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. It shows the reason: missing API username or password, an invalid ship-from or destination postal code, a missing CAD conversion 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 conversion rate. Magento has no product dimensions, so the rate is for the parcel weight only.

Tax is charged twice on shipping: set Use Canada Post prices without GST/HST/PST to Yes, or do not tax shipping in Tax Class for Shipping.

Test prices on a live store: set Sandbox to No and use the production API key.

Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached Canada Post rates.

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 and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_CanadaPostShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_CanadaPostShipping to remove the data, then bin/magento module:disable Vibefox_CanadaPostShipping, delete the folder app/code/Vibefox/CanadaPostShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached rates are always removed. If Remove data on uninstall is Yes, the Canada Post settings and the log are removed too. If it is No, the settings are kept for a re-install. The Canada Post services saved with orders (service and price source) stay with the orders.

Canada Post is a trademark of its respective owner. This module is not affiliated with or endorsed by Canada Post.