VibeFox Purolator for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions. 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

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 Purolator 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 fill in the Purolator API (live rates) section. For testing, turn on Development environment with the development key. Fill in Country prices or Fallback price if you want fixed prices or a fallback (see Configuration). Click Save.

On install the module creates the Purolator carrier with the delivery time text Purolator courier. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery 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 Purolator > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Purolator rates.

If live rates cannot work with the saved values (missing key, password or billing account, no Canadian ship-from postal code, no CAD rate), or there are neither API credentials nor fixed prices, a warning appears above the settings. A warning also appears if the shop weight unit is not one the module knows (kg, g, lb, oz and similar). Then product weights are taken as kg. Set the weight unit in International > Localization (Local units).

A number field that does not contain a number of 0 or more is not saved. A warning names the field and the value. The field is left empty, or gets its default for the weight fields. A wrong value in Country prices is saved as 0, and the warning lists the country and the column. If Min cart weight is greater than Max cart weight, nothing is saved and an error is shown.

General

Enable Purolator: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

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

Tax: the tax rule of the carrier, or No tax. It decides whether the shop adds tax on top of the shipping cost. For Canadian addresses the Purolator total already includes GST/HST/PST/QST. See Canadian sales taxes below.

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 carrier is hidden when there is none. The section has a link to the Purolator E-Ship Resource Centre, where you register and get the keys.

API key: your E-Ship Web Services key for the selected environment. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

API password: the password that belongs to the key. Like the key, it is not shown again after saving.

Billing account number: your Purolator account number. The estimates use the rates of this account. The development environment accepts the test account from the Purolator documentation. Clearing this field also removes the saved API key and password.

Development environment: uses the Purolator development environment (devwebservices.purolator.com) with the development key. The prices are test data. Turn it off on a live shop.

Ship-from postal code: the Canadian postal code parcels are sent from, for example L4W 5M8.

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: use Purolator prices without GST/HST/PST/QST. For Canadian addresses the Purolator total includes these taxes. Turn this on when the carrier has a tax rule in Tax, so the tax is not charged twice.

CAD → (shop currency) rate: Purolator prices are in CAD. If your shop 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.

Default product weight: in kg, used for each product that has no weight. Default: 0.5. Weights are converted from the shop weight unit 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 your shop default currency, tax excluded. Click Add country to add a row and the trash icon to remove one. Choose * Default (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 1–2 kg, M 2–3 kg, L 3–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. Both 9.99 and 9,99 are accepted. Rows without any price are not saved, and only one row per country 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 carrier for such countries.

Fixed price per: Order 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: in kg, hide the carrier when the cart weighs less. 0 means no limit.

Max cart weight: in kg, hide the carrier when the cart weighs more. Default: 30. 0 means no limit.

Minimum order amount: show the carrier only when the cart subtotal (after discounts, before tax) reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal (after discounts, before tax) 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.

Availability without shipping zones

Normally the carrier is offered in the zones it is assigned to in Shipping > Carriers.

Ignore shipping zones: offer Purolator for the countries below, whatever zone matches. On save the carrier is added to all zones, and zones created later are added too. Switching the option off removes those zones again.

Countries: the destination countries for that mode. Leave empty to use all active countries of the shop. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations to logs/vfd_prlr_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even with the debug log off. API keys, the billing account and customer postal codes are not logged. Turn the log off when you are done.

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 module deletes the settings, the carrier, cached rates and logs. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the Purolator price. Only physical products count: virtual products add no weight and are not included in the order amount. Before the customer enters an address, the price is estimated for the country the shop uses for estimates. 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 Purolator. Then it looks for a price: the live Purolator rate, then the country table, then the fallback price. If there is no price, the carrier 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, 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 (dimensional weight) are not sent. Purolator answers in French or English, by the customer's language. 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. The price is calculated in your default currency and then shown in the customer's cart currency.

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 carrier is hidden when there is no fixed price. The reason is written to the log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

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 carriers or fetch exchange rates automatically.

Orders

When an order is placed with a live Purolator rate, the service is saved with the order. Later recalculations of the cart do not change it. On the order page in the back office (Orders > Orders, open the order) a Purolator block shows Purolator service (name and code) and Live rate (excl. tax). Orders priced from the fixed prices or with free shipping have no such block.

License key

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

Purolator does not appear at checkout: check that the license is active and Enable Purolator 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. If Purolator gives no rate, the carrier is shown only with a country price, a * row or a Fallback price. Products can also be limited to certain carriers in the product page.

Live rates do not appear: look at the Log field on the module page. API errors are always there. Turn on Debug log and reload the checkout for details. With API keys the address must have a valid postal code (Canada) or ZIP code (USA). Also check the warnings above the settings.

HTTP 401 in the log: the API key or password does not match the selected environment. Development keys work only with Development environment on, production keys only with it off.

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 the carrier has a tax rule. Prices are converted with your CAD → (shop currency) rate.

A value disappeared after saving: read the warning shown after Save. 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: click Save on the module page. This clears the cached Purolator rates.

The page says the Purolator carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Purolator and choose Uninstall. The license key and the license status are always removed. The cached rates are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the saved Purolator services of orders and the log are removed. If it is off, the carrier is only disabled and all settings are kept; placed orders keep their Purolator service. Installing the module again, or a Reset, gives the carrier back the status it had before.

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