VibeFox Purolator 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, with the 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 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_purolator-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_purolator.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_purolator-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 this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Purolator 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 fill in the Purolator API (live rates) section: API key, password, billing account number, the Canadian ship-from postal code and, if your store currency is not CAD, the CAD rate. 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). Turn on Enable Purolator and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_purolator.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 extension type Shipping. Find VibeFox Purolator, 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 Purolator and save. If you install the extension again after an uninstall, the Purolator settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Purolator > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached Purolator rates. Only admin users with the modify permission for this extension can save the settings.

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 in the General section. It also says whether the fixed prices are used until then or the method is hidden. A warning also appears if the store weight unit is not one the extension knows. Then product weights are read as kg; add a weight class with the unit kg in System > Localisation > Weight Classes.

A number field that does not contain a number of 0 or more is not saved. A message after Save 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 message lists the country and the column. Nothing is saved, and an error is shown, if the method title is empty or longer than 64 characters, if Min cart weight (kg) is greater than Max cart weight (kg), if the sort order is not a whole number, or if the tax class or geo zone is not valid.

General

The customer sees one Purolator rate. The settings apply to every geo zone. You can limit the method to a geo zone or to countries in Availability.

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

Method title: the shipping method name shown to the customer at checkout. Default: Purolator. Required, 64 characters at most.

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

Sort order: the position of Purolator among the shipping methods at checkout. A whole number.

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 (Quick Estimate, by the total cart weight). If Purolator gives no rate, the fixed price is used, or the method 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. Error details go to the log, never to the customer.

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) 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. OpenCart has no store postal code, so it is not taken from the store address: enter it here.

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 store adds tax on shipping itself (a tax class in General), so the tax is not charged twice. Default: off.

CAD → (store currency) rate: Purolator prices are in CAD. If your store 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 (kg): used for each product that has no weight. Default: 0.5. Weights are converted from the product weight class 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 store default currency, tax excluded. Click Add country to add a row and the × button 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 method for such countries.

Fixed price per: Order (default) charges the price once. Item (price x 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 (default).

Max cart weight (kg): hide the method when the cart weighs more. Default: 30. If you leave it empty, 30 kg is used. 0 means no limit.

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

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which delivery is free. No request goes to Purolator then. Leave empty to never offer free shipping.

Availability

Geo zone: offer Purolator only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not checked when Ignore shipping zones is on.

Ignore shipping zones: offer the method for the countries below, whatever geo zone is selected.

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

Advanced

Debug log: writes rate calculations to storage/logs/vfd_prlr_debug.log.php (on OpenCart 4 system/storage/logs/vfd_prlr_debug.log.php). The file cannot be read 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. When the file reaches 5 MB, it is moved to vfd_prlr_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the Purolator settings and the log. When off, they are kept for a re-install. Cached rates are always removed. The Purolator service of placed orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key and password are 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 key and password are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Purolator price. If a Geo zone is set and the address is outside it, Purolator is not offered (unless Ignore shipping zones is on). 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 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 method is hidden.

With API credentials the extension 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 when the customer views the store in French, otherwise in English. Purolator returns the prices of all services; the extension 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, 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 does not trigger a new request. 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 extension 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 options or fetch exchange rates automatically. The customer does not see the Purolator service name, only your method title.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Purolator in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order is placed with a live Purolator rate, the service is saved with the order. In Sales > Orders the order page shows a Purolator panel above the history with Purolator service (name and code) and Live rate (excl. tax). The panel stays visible after the method is switched off. Orders priced from the fixed prices or with free shipping have no such panel. The order itself shows the method title and the shipping cost like any other OpenCart shipping method.

OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The saved Purolator service is updated with it to the latest live rate. If the order changes to another shipping method or to a price without a live rate, the saved service is removed from the order.

License key

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

Purolator does not appear at checkout: check that the license is active and Enable Purolator is on. Check Geo zone (or that Ignore shipping zones is on and the country is allowed), 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. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: look at the Log field on the extension 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 in the General section.

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 you set a Tax class. Prices are converted with your CAD → (store currency) rate.

A value disappeared after saving: read the message 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 extension page. This clears the cached Purolator rates.

The page says "Warning: You do not have permission to modify VibeFox Purolator!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_purolator (OpenCart 3) or extension/vfd_purolator/shipping/vfd_purolator (OpenCart 4) in System > Users > User Groups.

For developers: the Purolator API address can be replaced with the setting vfd_prlr_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 Purolator. The license key and license status of this extension are always removed. OpenCart always resets Enable Purolator, Sort order, Tax class and Geo zone. The cached rates are always removed. If Remove data on uninstall is on, the Purolator settings and the debug 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, and the saved Purolator services of orders are always kept.

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 Purolator in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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