VibeFox Purolator 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. Live rates are requested with the PHP cURL extension. The PHP SOAP extension is not required.

Purolator E-Ship Web Services (for live rates only): register for E-Ship Web Services in the Purolator E-Ship Resource Centre on the Purolator website. Purolator gives separate keys and passwords for the development and production environments. You also need your Purolator billing account number and 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-purolator-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/PurolatorShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PurolatorShipping 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 Purolator. 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 fill in the Purolator API (live rates) section. For testing, set Development environment to Yes and use the development key. Fill in Country prices or Fallback price if you want fixed prices or a fallback (see Configuration). Set Enable Purolator to Yes and click Save Config.

The module adds the Purolator shipping method to Magento. Customers see it as Purolator - Courier delivery (method title and method name). It is off after installation (Enable Purolator = No). The module also creates a table for the Purolator service of orders (see Orders).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Purolator, 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. Save Config saves the whole page. When a Purolator setting has changed, it also clears the cached Purolator rates. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a Min cart weight greater than the Max cart weight.

A number field that does not contain a number of 0 or more is not saved, and a warning names the field by its setting code, for example "fallback_cost". The field is left empty; the weight fields get their default. A wrong value in Country prices is saved as 0, and the warning lists the country and the column.

While Enable Purolator is Yes, warnings after saving remind you of settings that stop live rates: an API key, password or billing account is missing while another one is filled in, the ship-from postal code is not a valid Canadian postal code, or the base currency of your store is not CAD and there is no conversion rate. Without any API credentials and without fixed prices, a warning asks you to configure one of them. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable Purolator: shows or hides Purolator at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: Purolator. Required, at most 64 characters.

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

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

Purolator API (live rates)

With the API key, password and billing account filled in, the price comes from the Purolator E-Ship Estimating web service. If Purolator gives no rate, the fixed price is used, or the method is hidden when there is none. Opening or saving the settings never sends a request to Purolator.

API key: your E-Ship Web Services key for the selected environment. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.

API password: the password that belongs to the key. It is stored and shown the same way as the key.

Billing account number: your Purolator account number. The estimates use the rates of this account. Spaces and dashes are removed. Clearing this field also removes the saved API key and password.

Development environment: Yes uses the Purolator development environment (devwebservices.purolator.com) with the development key. The prices are test data. Set it to No on a live store. Default: No.

Ship-from postal code: the Canadian postal code parcels are sent from, for example L4W 5M8. Spaces are removed. Without a valid Canadian postal code no request goes to Purolator.

Service in Canada: Cheapest available (default), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM or Purolator Express Evening.

Service to the USA: Cheapest available (default), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM or Purolator Express U.S. 12:00.

International service: Cheapest available (default), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM or Purolator Express International 12:00.

If the chosen service is not offered for the address, the cheapest available one is used.

Canadian sales taxes: Yes removes GST/HST/PST/QST from the Purolator total. For Canadian addresses the Purolator total includes these taxes. Set it to Yes when your store charges tax on shipping (a tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping), so tax is not charged twice. Default: No.

CAD to base currency rate: Purolator prices are in CAD. If the base currency of your store 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 and the fixed prices apply. If your base currency is CAD, leave it empty.

Default product weight (kg): used for each product that has no weight when the live rate is requested. Default: 0.5. Weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs) and sent to Purolator as the total weight in whole pounds, rounded up.

Fixed prices (used without API credentials, and as the fallback when the API gives no rate)

Country prices: a price by country and cart weight in the base currency of your store, tax excluded. Click Add country to add a row and Delete to remove one. Choose * All other countries for a row that covers every country without its own row. Each row has a Base price and size columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. An empty or zero size price uses Base. A Base of 0, or an empty Base, means free shipping for the weights without their own size price. Rows without any price are not saved. If a country has several rows, the last one is kept.

Fallback price: the price for a country that has no row in Country prices and no * row. Leave it empty to hide the method for such countries. 0 means free.

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 shipment.

Conditions

Min cart weight (kg): hide the method when the cart weighs less. 0 means no limit.

Max cart weight (kg): hide the method when the cart weighs more. Default: 30. 0 means no limit, an empty field means 30 kg.

Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal (calculated the same way) from which delivery is free. No request goes to Purolator then. Leave empty to never offer free shipping.

The cart weight for these conditions counts products without a weight as 0. Magento products have no standard dimensions, so dimensional weight is not calculated.

Ship to Applicable Countries: All Allowed Countries (default) offers Purolator for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. If no country is selected, the method is not offered anywhere.

Advanced

Debug log: writes rate calculations to var/log/vfd_prlr_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. API keys, passwords, the billing account and customer postal codes and cities are not logged. At 5 MB the log is moved to an old copy and a new one is started. Turn the log off when you are done.

Log contents: 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 Purolator settings and the log (see Uninstall). Only the value of the Default Config is used. The license key and the cached rates are always removed. The Purolator service of orders is never deleted.

How it works at checkout

At the shipping step Magento asks the module for the Purolator 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 Purolator. A Magento cart price rule with free shipping also makes the price 0, without a request to Purolator; the country, weight and minimum amount conditions still apply. Then it looks for a price: the live Purolator rate, then the country table, then the fallback price. If there is no price, the method is hidden.

With API credentials the module sends Purolator a Quick Estimate request: your billing account, the ship-from postal code, the customer's city, province or state code, country and postal code, and the total cart weight in whole pounds. For Canada a valid postal code is needed, for the USA a valid ZIP code; other countries are sent with the postal code as entered. Dimensions are not sent. Purolator answers in French when the locale of the store view is French, otherwise in English. Purolator returns the prices of all services; the module takes your chosen service or the cheapest one, removes Canadian sales taxes if set, and converts the price from CAD to 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. A failed request is cached for 10 minutes, so a Purolator outage does not slow down every checkout refresh. The API timeout is 10 seconds.

If Purolator gives no rate (API down, wrong credentials or postal code, service not available, no CAD rate), the customer sees no error. The fixed price is used, or the method is hidden when there is no fixed price. The reason is written to the log.

The module calculates rates only. It does not create Purolator shipments, print labels, book pickups, handle returns or track parcels. It does not use the Full Estimate (dimensions, several pieces, options such as signature or dangerous goods), show delivery dates, show several services as separate methods or fetch exchange rates automatically. Customers see the method title and name, not the Purolator service.

Orders

When an order is placed with a live Purolator rate, the module saves the service and the rate with the order. Later recalculations do not change it. On the admin order page (Sales > Orders > View, Information tab) a Purolator block shows Purolator service (name and code) and Live rate (excl. tax) in the base currency. Orders priced from the fixed prices or with free shipping have no such block. The block also works for older orders and when the module is switched off.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Purolator is the first row of the VibeFox Purolator 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-purolator 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 Purolator method is not shown to customers at checkout and no rate is requested or 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

Purolator does not appear at checkout: check that the license is active and Enable Purolator 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. If Purolator gives no rate, the method is shown only with a country price, a * row or a Fallback price.

Live rates do not appear: look at the Log contents field in the Advanced section. API errors are always there. Set Debug log to Yes and reload the checkout for details. The address must have a valid postal code (Canada) or ZIP code (USA). Also check the warnings shown after Save Config.

HTTP 401 in the log: the API key or password does not match the selected environment. Development keys work only with Development environment = Yes, production keys only with No.

The rate differs from the Purolator website: the Quick Estimate uses the rates of your billing account and the total weight rounded up to whole pounds, without dimensional weight. For Canadian addresses the total includes sales taxes; use Canadian sales taxes if your store taxes shipping. Prices are converted with your CAD to base currency rate.

Canadian tax is charged twice: the Purolator total already includes GST/HST/PST/QST. Set Canadian sales taxes to Yes, or do not tax shipping in Tax Class for Shipping.

A value disappeared after saving: read the warning shown after Save Config. The value was not a number of 0 or more, so it was not saved. Enter it again as a plain number.

Rates look outdated after a change: change a Purolator setting and click Save Config on the Delivery Methods page. This clears the cached Purolator 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_PurolatorShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PurolatorShipping to remove the data, then bin/magento module:disable Vibefox_PurolatorShipping, delete the folder app/code/Vibefox/PurolatorShipping 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 Purolator settings and the log are removed too. If it is No, the settings are kept for a re-install. The Purolator service of orders stays with the orders and is shown again after a re-install.

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