Canada Post credential requirements

Prior to shipping with Canada Post, you must configure credentials in the Shipium Console. You'll provide your Canada Post customer number, which you can find more about in the Business Details section of Canada Post's documentation, and a Canada Post contract number. You'll also need to enter your API username and API key for both production and test mode.

Configure your Canada Post billing account

To set up your Canada Post account within the Shipium platform to use Canada Post's contract shipping billing structure, you'll need to configure this carrier account for third party billing.

First, you'll log in to the Shipium Console and select Configure and then Fulfillment Contexts from the left navigation menu.

You'll select the fulfillment context for which you wish to enable billing for Canada Post. If you haven't yet established a fulfillment context, you can find details about how to do so in the Fulfillment Contexts documentation.

Prior to setting up the third party billing account, you'll need to have a carrier contract configured for Canada Post. If you don't have a Canada Post contract linked to a fulfillment context in your network, you can find directions for configuration in the Carrier Contracts documentation.

Within the selected fulfillment context, you'll select the Third Party Billing tab.

Once you select Add Third Party Billing, you'll provide a group name for the billing group. Optionally, you can also provide a description and unique identifier.

The details for your newly created third party billing group will appear on the Third Party Billing tab home screen.

Next, you'll select Add in the Accounts section on the page to create a new third party billing account for the third party billing group.

After selecting Canada Post from the dropdown Carrier menu, you'll provide the required Account Name. You also can provide an optional Description.

For Credentials, you'll provide your Canada Post Third Party Customer Number. You can log in to your Canada Post account and check the "Business details" section in Canada Post's documentation for information about your customer number.

To indicate the party responsible for payment of the shipment and taxes and duties, you'll opt for the Shipper or 3rd Party. The Shipper is the account initiating the label request. The 3rd Party is the entity for whom the package is being requested.

The Canada Post account will display in your Third Party Billing tab.

QR codes for return labels

Canada Post supports printerless return labels using QR codes that customers can scan at Canada Post locations without printing a physical label. This feature is ideal for return shipments where customers may not have access to a printer.

How it works

When you request a printerless label for Canada Post returns, the response includes a QR code image and the URL encoded within it. Customers can display the QR code on their mobile device at a Canada Post location to have their return label printed.

Configuration requirements

To use QR codes for Canada Post returns, you must configure a separate returns carrier method in your fulfillment context, even if carrier rating is enabled for regular Canada Post shipments. The Fulfillment Contexts documentation provides guidance for configuring a returns fulfillment context.

Request a QR code

To generate a QR code for a Canada Post return label, you'll include "printerless" in the labelFormats array and provide the printerlessParameters configuration when calling the Return Label API.

The following fields must be included in your call request.

Example request

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "labelFormats": ["printerless"],
    "printerlessParameters": {
      "type": "qrcode",
      "imageFormat": "jpeg"
    },
    "includeLabelImagesInResponse": true,
    "contentDescription": "General Merchandise"
  },
  "destinationAddress": {
    "addressType": "commercial",
    "company": "Shipium Warehouse",
    "name": "Attn: RETURNS",
    "street1": "1234 Warehouse Way",
    "city": "Reno",
    "state": "NV",
    "postalCode": "89521",
    "countryCode": "US"
  },
  "originAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "street1": "123 Warehouse St.",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 5,
      "width": 5,
      "height": 5
    }
  },
  "totalWeight": {
    "weight": 50,
    "weightUnit": "lb"
  },
  "customerReturnParams": {
    "fulfillmentContext": "8ad8e1a8-0656-4d18-afe8-d24fe3fc5f94"
  }
}

Example response

The response includes a printerlessInfo object within the documents array containing metadata about the QR code.

{
  "carrier": "canadapost",
  "carrierServiceName": "Canada Post Returns",
  "documents": [
    {
      "labelFormat": "printerless",
      "labelImage": {
        "imageEncoding": "base64",
        "imageContents": "/9j/4AAQSkZJRgABA...",
        "imageFormat": "jpeg"
      },
      "printerlessInfo": {
        "type": "qrcode",
        "valueRepresented": "https://ct.soa-gw.canadapost.ca/esto/app/bypass/label?key=d99978d9569c477cb4b68f071cac4806"
      }
    }
  ],
  "shipiumCustomerReturnLabelId": "4c6af31c-6f1d-4b20-a16f-a9110135e442",
  "status": "success"
}

Response fields related to the printerless label include:

• labelImage.imageEncoding. The encoding of the image contents (will be "base64")
• labelImage.imageContents. Base64-encoded image of the QR code that can be displayed or printed
• labelImage.imageFormat. The image format of the QR code (e.g., "jpeg")
• printerlessInfo.type. The type of printerless label (e.g., "qrcode")
• printerlessInfo.valueRepresented. The Canada Post URL encoded in the QR code; you can use this URL to generate your own QR code if needed.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support