canada post logoCanada Post Module

Offer real-time rates to customers and provide shipping quotes on the product and cart pages.

Developed by Zack Hussain @ zhmedia.ca

  1. Installation & Configuration
  2. Upgrading From Version 3.x
  3. Notice for PrestaShop 1.6.0.0 to 1.7.0.5
  4. Rates
  5. Boxes & Box Packing
  6. Rate Discount Rules & Free Shipping
  7. Delivery Time Estimates
  8. Shipping Estimator
  9. Addresses
  10. Setting Up Cron Job
  11. Smart Caching
  12. Troubleshooting
  13. Common Error Messages
  14. Requirements
  15. Changelog

Installation & Configuration

  1. Go to the Modules page.
  2. Search for “Canada Post” and click Install
  3. If you don’t see the module, click Upload a Module and upload the module .zip file.

The module must be configured with your Canada Post account, an origin address, and at least one box.

To configure the module:

  1. Go to Modules page.
  2. Find the Canada Post module and click Configure.
  3. Click Sign in with Canada Post
  4. You’ll be redirected to the Canada Post website where it will prompt you to login to your account and authorize the module to create shipments on your behalf. You can revoke these permissions at any time from the Canada Post website.

If this is your first time creating a Canada Post account and/or adding a new credit card to your Canada Post profile, please allow up to 24 hours for your information to process before using this module. You may encounter errors during that time.

Upgrading From Version 3.x

Notice for users upgrading the module from any version prior to 4.0.0: While care was taken to ensure a smooth update, it is highly recommended to uninstall and reinstall the module as version 4.0.0 is completely re-written from scratch and there’s a possibility of encountering errors.

There are also several dozens of new configuration and customization options in version 4.0.0 that are not in prior versions which should be configured immediately after updating.

Notice for PrestaShop 1.6.0.0 to 1.7.0.5

PS versions 1.6.x and early versions of PS 1.7 contain bugs that this module must work around.

For versions 1.6.0.0 to 1.7.0.5, this module automatically installs an Override file at {your_prestashop}/override/classes/Hook.php to solve a particular bug. Before using the module, verify that this file present. If you encounter the error “Invalid id_module or hook_name”, try clearing your cache in Advanced Parameters > Performance and click “Clear Cache” in the top right.

If you still encounter the above error, compare the following two files to see that there isn’t another module attempting to override the same function in the same file: {your_prestashop}/override/classes/Hook.php and {your_prestashop}/modules/canadapostrates/override/classes/Hook.php. As a last resort, you can manually transfer the module’s Hook.php contents into the Hook.php file in your store’s override/classes folder.

In PS 1.7.0.0 to 1.7.0.5, you may also need to alter one line of your theme to get the front-office order tracking feature to display properly - add “nofilter” to the following hook:

  1. Open the file {your_theme}/templates/customer/order-detail.tpl
  2. Replace {$HOOK_DISPLAYORDERDETAIL} with {$HOOK_DISPLAYORDERDETAIL nofilter}

Rates

The checkout rates can be configured by selecting the carriers you wish to enable in the Rates preferences. Enabling carriers in the Rates preferences will install them in your back-office automatically (Shipping > Carriers).

The Rates preferences include various settings for Box Packing which are explained in the next section.

If you are not seeing the rates after enabling the carriers, please see the Troubleshooting section.

Boxes / Box Packing

Add all the box dimensions that you ship orders with in the Boxes preferences.

The module uses a sophisticated box packing algorithm to determine the smallest box(es) that will fit all the products in the customer’s cart; it can split the products into multiple boxes when the cart has more products than your largest box can fit.

You can add unlimited boxes into the module from the configuration page. The more boxes you add, the more accurate the rates will be.

You can disable product splitting and only use 1 box for each cart by setting Multiple Box Rates to Off. This will show standard rates for a single box; the module will still use box packing to determine the best box to use.

The Multiple Box Rates setting determines how the module sums up the rates for each box:

Off: Disables multiple boxes and only uses 1 box.

Simple & Fast (recommended): Finds the rate for the LARGEST required box and
MULTIPLIES the rate by the amount of boxes needed. e.g. For 3 boxes:
$10 * 3 boxes = $30 Shipping Fee. This method only calls the Canada
Post API once to get the rates for the cart.
Accurate & Slower: Finds the rate for EVERY box required to fit all
the products in the cart and SUMS all the rates together. e.g. For 3
boxes: $10 + $11 + $12 = $33 Shipping Fee. This method will call the
Canada Post API once for each box that the cart requires. Carts
requiring many boxes may have a longer loading time when retrieving
rates. If your store has a lot of traffic, you may reach your Canada
Post API throttle limit which results in an API timeout for 60
seconds. You can request an increased API limit from Canada Post -
more info on the throttle limit can be found here:
https://www.canadapost.ca/cpo/mc/business/productsservices/developers/throttlelimits.jsf

If the cart products require more boxes than the maximum allowed, the module will choose boxes that fit the largest products in the cart until it reaches the maximum.

The Canada Post weight limit per box is 30kg and the module will spread weight across multiple boxes if required.

The limit of boxes per cart is 25.

Possible Issue: If the cart contains a product that does not fit in any of your boxes, the module will be unable to pack the products into your boxes and will revert to using (1) of the largest box you have. The module will display a warning on the configuration page if any of your products are too large for your largest box.

Rate Discount Rules & Free Shipping

You can configure discounts for each Canada Post carrier in the Rate Discount Rules preferences.

Each carrier can have a percentage, dollar amount, or Free Shipping discount applied to it. e.g. Free Shipping when Order Total Is At Least CAD$100.00 tax excl.

You can only create one discount rule per carrier for each Shop.

If you require more flexible ranges, consider using PrestaShop’s built-in carrier system using the following example as a starting point:

In this example we will offer free shipping for only Canada on orders above $100.

  1. Create a new zone called “Canada” (International > Locations > Zones menu).
  2. Edit the country Canada and change its zone from North America to Canada (International > Locations > Countries menu). Zones are only used for Shipping, so update any other carriers with the new Zone if needed.
  3. Create a new carrier called “Free Shipping” (or any other name).
  4. Set its Billing to ‘According to total price’.
  5. Set its Out-of-range behavior to ‘Disable Carrier’.
  6. Set its range to ‘>= 100’ and ‘< 999999’.
  7. Deselect all zones except Canada, and set Canada to 0.00 This will display free shipping for Canada orders when the order total is above $100.00. To disable one or more carriers when free shipping is enabled, do the following for each carrier.
  8. Edit a Canada Post carrier.
  9. Set its Billing to ‘According to total price’.
  10. Set its Out-of-range behavior to ‘Disable Carrier’.
  11. Set its range to ‘>= 0’ and ‘< 100’. This will disable that particular carrier when the order total is above $100.00. Repeat for each carrier you wish to disable.

Delivery Time Estimates

To display delivery time estimates on the checkout page (e.g. 3 Business Days), you must edit one line of code on your theme. Use the following instructions to enable delivery times.

  1. Enable Show Delivery Time Estimates in the Rates preferences.
  2. Open the file at /themes/(your_theme_name)/templates/checkout/_partials/steps/shipping.tpl 3. Near the top, locate the following line: {block name='step_content'} 4. Immediately after that line, paste the following code: {if isset($delay_times)}{assign var=delivery_options value=$delay_times}{/if}

Shipping Estimator

The Shipping Estimator allows guests/customers to estimate shipping fees on the Product and Cart pages. To display the Shipping Estimator, enable the Enable Shipping Estimator setting in the Rates preferences.

To estimate rates, guests without addresses can enter a Country & Postal/Zip Code, and customers with addresses will see rates based on their account’s shipping address. Customers with addresses can select which address they wish to estimate shipping rates for.

On the Product page, the shipping estimates are based on the product that the customer is currently viewing along with any products already in their cart, any carrier restrictions for those particular products will apply.

When a guest/customer adds a product to their cart, the Shipping Estimator will then allow the customer to change their cart’s selected shipping method from the Product or Cart pages.

Addresses

Configure your addresses in the Addresses preferences.

Select one address as your Origin address to be used as the origin for front-office rate calculation.

Only the origin address is used in this module.

Setting Up Cron Job

What is Cron

Cron is a Unix system tool that provides time-based job scheduling: you can create many cron jobs on your server which are then run periodically at fixed times, dates, or intervals.

This module uses Cron Jobs for the following two tasks:

  1. Track all shipped orders and auto-update their order status when they are delivered by Canada Post.
  2. Clear cached front-office rates that are older than 3 months.

How to set it up

  1. Install the free “Cron tasks manager” module by PrestaShop by going to the “Module Catalog” page and searching for “Cron” and clicking “Install”.
  2. Go to the “Cron tasks manager” configuration page and change “Cron mode” to “Advanced”.
If you are comfortable setting up a cron job on your own server:
Copy the cron command from the “Cron tasks manager” module and paste it in your server’s cron manager (varies by server). Set the cron job to run hourly (0 * * * *).
If you’re not comfortable setting up a cron job yourself, or you don’t have a developer who can do it for you:
Consider using the service EasyCron (free for 200 cron jobs per day): https://www.easycron.com/cron-job-tutorials/how-to-set-up-cron-job-for-prestashop-cron-tasks-manager - and configure the task to run hourly.

Smart Caching

The module stores rates for each cart in the database to speed up your website. It will only retrieve new rates if the customer changes their zip/postal code, the products in their cart, or the quantities for products already in their cart.

In some cases you may be trying to change the module configuration/carriers and refreshing your website to see updated rates. The rates will not update until one of the above conditions have been met, so try changing the products/quantities in your cart to see the new rates.

If you have the free “Cron task manager” module by PrestaShop installed, the module will regularly delete cached front-office rates older than 3 months (cpr_cache & cpr_cache_rate tables) to save space.

Troubleshooting

Q: Why are the rates not showing up?

Enable Error Logging in the module configuration page to help troubleshoot rates. If there are any errors while retrieving rates, the errors will get logged in the Advanced Parameters > Logs menu. Search for "Canada Post" in the log page to filter your logs.

Common Error Messages

“Rejected by SLM Monitor”
You have exceeded the throttle limit for your API key. You will be blocked from making additional calls for up to a minute. You can request for a limit increase using the “Increase Limits” link found below your API keys on canadapost.ca.

Requirements

  1. A Canada Post account.
  2. Your website’s PHP version should be at least 5.4.0

Changelog