Use Cases for Canada Post Web Services

The diagram below illustrates a scenario where Canada Post web services have been integrated into an online store. Select the links in the diagram to get further details.

Services in an e-commerce workflow

The following shipping use cases describe and illustrate the web service calls to invoke to perform these tasks.

• Get rates for shipping services
• Print shipping labels
• Print shipping and return labels
• Get Canada Post charges
• How to use ad hoc and batch call patterns
• Synchronize calls
• Transmit shipments to receive a manifest
• Retrieve manifest details
• Track orders from your website
• View signature image or Delivery Confirmation Certificate

Get rates for shipping services

When you call Get Rates, you provide the characteristics of a given parcel in your request. All eligible shipping services and costs will be returned in the XML data. You or your customer (depending upon your implementation) can then select the preferred shipping method based on speed and cost.

Figure 1. Get rates for shipping services

Print a shipping label (plain paper or thermal)

When you create a shipment, you can specify the following:

• Labels in thermal or plain paper format.
• PDF encoding for the labels.
• Email notification options for tracking. (For commercial customers, shipment tracking events begin once the manifest has been transmitted.)

The image below illustrates the minimum call set to receive a label image.

Figure 2. Print a shipping label

Print a domestic shipping label with return label

You may want to print a return label to include with an outgoing shipment. The return label is not billed to your account until it is affixed to the outside of a return shipment and passes through the mail stream.

The domestic shipping label and the return label links are returned to you in the same single response to the “Create Shipment” request providing you supply return label details with your request. You can invoke the label links in any order (shipping label first or return label first.)

Figure 3. Print domestic shipping label and return label

Get Canada Post charges for a shipment

You can make a call to retrieve the Canada Post charges for your domestic, U.S.A. or international shipment. Add the call “Get Shipment Price” to any use case that starts with Create Shipment.

Figure 4. Optional call for charge information

Ad hoc or batch call patterns

You can execute the above label printing use cases using one of two call patterns:

• Ad hoc – one at a time as a packer is ready for it.
• Batch – store many orders and then print them all at once.

Shipment information is stored on Canada Post servers from the time you create it until 90 days after it is transmitted. The diagram below shows how to execute ad hoc and batch patterns.

Figure 5. Ad hoc and batch call patterns

Synchronize calls for shipments

Your application can store links for later use (as described in the batch call pattern) or your application can use the synchronization calls to retrieve links from Canada Post. If your application normally stores links but suffers a failure and loss of data, the synchronization calls can be used to recover from the data loss.

Figure 6. Synchronize calls for shipments

Transmit your shipments to receive a manifest

Unless you use only one group, it is best to start with the synchronization call “Get Groups” to determine which groups contain shipments eligible for transmit.

The purpose of a group-id is to group several shipments together to include on the same manifest.

Performance limitations
To avoid a timeout of our servers, please follow these recommendations:

• Do not include more than 30 groups per manifest (i.e., maximum of 30 group-ids in one Transmit Shipments request.)
• Do not put more than 5,000 shipments in one group.

System limitations
To avoid an error, please do not exceed the following limits before performing a Transmit Shipments call:

• Maximum of 50 groups per manifest (error 9109 if exceeded).
• Maximum of 10,000 shipments in one group (error 9110 if exceeded).
• Maximum of 10,000 shipments across multiple groups (error 9108 if exceeded).

The group-at-a-time transmit pattern is shown below. You could also loop your transmits per group, storing all the manifest links before looping for the manifest artifacts.

Figure 7. Transmit shipments to receive manifest

Retrieve manifest details

Manifest details are available as XML data. Links to the data are returned at the same time as links to the manifest document from a “Get Manifest” request.

To retrieve the XML data, add an invocation of “Get Manifest Details” in the process flow pictured above in Transmit shipments to receive manifest before or after invoking the artifact link. You can use the XML details to update your back-end accounting systems.

If manifest links are lost or intentionally not stored, you can use the synchronization call “Get Manifests” with a date range of today’s date to retrieve links for all manifests created by transmit requests.

Track orders from your website

Calls to Get Tracking Summary and Get Tracking Details allow customers to track their orders directly from your website.

Figure 8. Track orders from your website

View signature image or Delivery Confirmation Certificate

Your customer service staff can get the same tracking information as shown above in Track orders from your website. In addition, they can retrieve the signature image or view the Delivery Confirmation Certificate.

Figure 9. View signature image or Delivery Confirmation Certificate