Update! - This article is maintained for reference only.

Get the current release of CPSOL here.

Update! - March 28, 2010 - Code files are no longer available for this article.

Article about recent implementation of the Canada Post Shipping Module in VirtueMart 1.1.3.

The project used Joomla/VirtueMart open source components to create an online store. The shop required integration to Canada Post's Shipping Module. This article discusses implementation of the Canada Post shipping module that ships with the stable release of VirtueMart. Several modifications were made to address functionality gaps required for this project.

Joomla 1.5.5 and VirtueMart 1.1.3 (VM) versions were used.

Definitions

Joomla! - www.joomla.org, open source content management system

VirtueMart – www.virtuemart.net, open source e-commerce application that is an installable component in Joomla.

Canada Post Shipping Module – (canadapost.php, canadapost.cfg.php) a component included in VirtueMart that prepares and receives XML requests for shipping rates within VirtueMart.

CPC Sell OnLine – http://sellonline.canadapost.caCanada Post Corporation interface that handles XML request from third parties – receives request, calculates rates based on XML document and user account Profile.

CPC Profile – Canada Post Corporation Sell OnLine user account used to select shipping rate options.

Issues with VM Canada Post Shipping Module

The following issues with the VM Canada Post Shipping Module were resolved in this project:

1. Date formats incorrectly on US bound shipment for small parcel where CPC response returns string other than a date (“2 to 4 weeks” or “up to 2 weeks”).

2. Tax calculations; GST should not be added to shipments outside of Canada, tax amount not calculating correctly due to rounding differences.

3. Display in Joomla formats incorrectly when CPC Shipping Module is used without Standard Shipping Module displaying below it (US bound shipments in this case).

4. French language is literal string in rate display over riding canadapost.cfg.php setting.

5. Additional comments returned by CPC do not display.

6. Shopper Group parameter “Show price including tax” not handled, causing incorrect values to display on cart payment method step.

7. Handling fee set in CPC Profile not added to rates.

8. Default server is no longer correct – should be sellonline.canadapost.ca

9. Module does not handle “ready to ship” request/response.

10. Module does not handle UOM for product dimensions or weight – values recorded in product are not used.

11. Ship to and Bill To postal codes should use input mask in user registration to prevent error due to invalid code.

12. Shipping charges in PayPal are correct giving correct order total, but do not display properly; shipping tax omitted when parameter “include tax in price = y”, and shipping tax added to item total when parameter “include tax in price = n”.

Issue: 12 needs to be be fixed in PayPal code – to be done.

Canada Post Sell OnLine

Canada Post (CPC) provides an interface called “Sell OnLine” that allows third party applications to submit an XML request and receive an XML response for shipping rates. The rates are dependent on settings in the shippers Profile. Before you can set up a profile you need to register an account with CPC and then submit an email request to create a Profile.

Links to CPC resources:

Main Sell OnLine site that has developer resources including status codes, faq's.

Developer Resources

Sample HTTP Request to Sell OnLine for testing

Login to CPC Profile

Setting up CPC Profile

For this implementation the key parameters to set in CPC Profile were:

1. General Information – include fuel surcharge set to YES

2. General Information – Sell OnLine Status – set to test to just calculate rates

3. Shipping Services – select service options for Domestic, US and International

4. Boxes – Input the sizes of available shipping boxes.

5. Handling Fees – (optional) Set handling fees by item count ranges.

CPC uses volume calculations to determine how many items can fit into the box types defined. The box selected will be the one where the most items fit, so box definition and product dimensioning are critical. It should be understood that Sell OnLine is designed for shipments of one to five items. It can handle more, but response time may become a limiting factor. A potential optimization for clients shipping higher numbers of items in one order would be to predetermine packaging (figure out number of packages to hold items) and then send request for package containing ordered items.

In this project we added the elements <handling/> for handling charge calculation and <readyToShip/> to the XML request to allow bypassing the volume calculation. The published schema, eParcel.dtd, for Sell Online has a few more elements that could be utilized, but are not required in this project. As well, there are other settings in the CPC Profile that determine how rates are calculated (e.g. Free Shipping) that were not part of this implementation.

After setting Profile configurations the CPC set up was tested using the HTTP interface by changing values and submitting a request.

VirtueMart Configuration

Once the Sell OnLine Profile has been configured and tested VirtueMart's Canada Post Shipping Module is configured. The Sell OnLine Shipping Module is selected in VM Configuration -> Shipping. Then the module parameters are set in Store -> Shipping Module List -> Canada Post Configure Shipping Method. The only settings that need to be changed (using canadapost.php version 1.1) are; Merchant ID, Use Ready To Ship (Yes/No), Arrival and Handling descriptions. The default CPC_XML_DEMO id is only good for connectivity testing. A site specific CPC Profile is required because settings can not be configured for CPC_XML_DEMO, so rates will probably not be what's expected.

Product Settings

Each product requires dimensional and weight data that is passed to CPC Sell OnLine, which uses the data in volume and rate calculations. Important considerations:

1. VM Product unit of measures can be anything - “fiddle sticks” is acceptable.

2. Zero or null dimension values are handled – CPC Sell OnLine only needs a weight value however the rate will most likely be incorrect if you are not working in kilograms.

3. CPC Sell OnLine assumes dimensions are in centimeters and weight is in kilograms.

4. VM Product dimensions and weights must be entered explicitly – 100 g must be entered as “0.1” - entering “.1” will set the value to “1”. This is the orginal functionality - revised code evaluates string in uom measure field for "grams", "pounds", "ounces" and defaults to "kilograms" for anything else.

5. If “Use Ready To Ship” is set to YES each product dimension / weight is used to calculate rates – items are not combined in packing boxes.

6. No testing was done with Product unit settings – left at default values.

A potential optimization/improvement would be to create a module/plugin for units of measure to simplify user input and application handling of values. This should be at the product level. Also, it would make more sense to add a ready to ship flag at the product level versus where it is now, the module level.

User Settings

The site was configured so a user has to register before an order can be placed. During the user configuration process a Bill To address has to be maintained. Important considerations:

1. There is no input mask or validation of postal code – “BBBBB” is acceptable – CPC Sell OnLine returns an error message for invalid values.

2. CPC Sell Online only uses Country and Postal Code to determine rates – street, city can be null in the XML request.

3. Users can have multiple Ship To addresses – selected address is used for rate calculation.