VibeFox Purolator for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later. 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_purolator folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Purolator, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. 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).

6. Add VibeFox Purolator to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Purolator. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name customers see for this zone. Leave it empty to use the global Method title.

Every time you save the settings, the cached Purolator rates are cleared. If live rates cannot work with the saved values (missing key, password or 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.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. A zone can override it. Default: Purolator.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. See also 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 method is hidden when there is none.

API key: your E-Ship Web Services key for the selected environment.

API password: the password that belongs to the key.

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.

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

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: for Canadian addresses the Purolator total includes GST/HST/PST/QST. Turn on Use Purolator prices without GST/HST/PST/QST when Tax status is Taxable, so the tax is not charged twice.

CAD → (store currency) rate: Purolator prices are in CAD. If your store 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 store currency is CAD, leave it empty.

Default product weight (kg): used for each product that has no weight. Default: 0.5. Weights are converted from the store 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 the store currency. Click + Add country to add a row and the cross 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. Rows without any price and invalid country codes are removed when you save. 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 method 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 (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.

Minimum order amount: show the method only when the cart subtotal reaches this amount. Leave empty to always show it.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Free shipping from: the cart subtotal from which delivery is free. It applies only where the method has a price: a country price or the fallback price (then no request goes to Purolator), or a live rate. Leave empty to never offer free shipping.

The cart weight for these conditions counts products without a weight as 0. Prices and weights accept a comma or a point as the decimal separator.

Availability without shipping zones

Ignore shipping zones: offer Purolator for the countries below even if the method is not added to any shipping zone.

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

Advanced

Debug log: writes rate calculations to WooCommerce > Status > Logs (source "vfd-purolator"). 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.

Remove data on uninstall: when on, deleting the plugin removes its settings, zone methods and cached rates. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. 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. If free shipping applies, the customer sees the method at no cost.

With API credentials the plugin 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 returns the prices of all services; the plugin takes your chosen service or the cheapest one, removes Canadian sales taxes if set, and converts the price from CAD. The service is saved with the order as Purolator service and is visible on the admin order screen.

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 method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

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

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Purolator. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Purolator is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Purolator does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. 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: open WooCommerce > Status > Logs, source "vfd-purolator". API errors are always there. Turn on Debug log for details. With API keys the address must have a valid postal code (Canada) or ZIP code (USA).

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 WooCommerce adds tax on shipping. Prices are converted with your CAD → (store currency) rate.

Rates look outdated after a change: save the settings page. This clears the cached Purolator rates.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods and cached rates are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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