Ship parcels

Getting started

Before integrating our shipping APIs, make sure you complete the following prerequisites and setup steps. For a more detailed overview, refer to the QuickStart guide. 

Prerequisites

Please note: To use our APIs, you must first have a valid Canada Post business account, which provides a customer number. Commercial customers typically have a formal commercial contract, which also provides a contract number and is billed to a credit account. Solutions for Small Business™ customers can access the API using their small business account number. Returns services are generally billed to the credit card on file in your profile or business account.  

Once you have an account, here are the next steps to use the API:

1. Create a canadapost.ca user ID.
2. Join the Canada Post Developer Portal.
3. Get your production and test API credentials (API Key and API Secret). 

API endpoints

Production environment

https://api.canadapost-postescanada.ca/prod/devportal-portaildesdeveloppeurs/shipping/v1/{mailedBy}/{mobo}/shipment 

Required headers

Available shipping services

We offer both domestic and international shipping services. Below is a categorized list of commonly supported services, including the service codes required for all API requests.

International services

Shipping options

 Shipping options are selected by providing the appropriate optionCode (for example, SO or COV) in your API requests. Options can be used together or independently, though some may conflict with others or require additional data. 

View a full list of valid codes and their descriptions

Shipping options sample request

{ 
  "serviceCode": "DOM.XP", 
  "options": [ 
    { 
      "optionCode": "SO", 
      "optionAmount": "0.00" 
    }, 
    { 
      "optionCode": "COV", 
      "optionAmount": "100.00" 
    } 
  ] 
} 

Non-delivery handling options

For international and U.S. shipments that are undeliverable, a non-delivery handling instruction must be specified in the API request. This determines the parcel’s fate if delivery fails.

Please note: These options are required for many services, particularly commercial-format parcels like International Parcel – Air/Surface and Expedited Parcel™ – USA. Omission for required services will result in a validation error.

Packaging indicators

These indicators are passed in the parcelCharacteristics element of your API request. They impact rate calculation and handling.

Important implementation notes:

• You must manually set mailingTube or unpackaged to true if your item meets those conditions.  
• The API will typically set the oversized flag automatically if you provide dimensions that exceed the maximum size thresholds.  
• We only apply one surcharge. If the unpackaged surcharge applies, the oversized surcharge will be waived. 

Packaging indicator sample request

{ 
  "parcelCharacteristics": { 
    "weight": 1.2, 
    "dimensions": { 
      "length": 60, 
      "width": 10, 
      "height": 10 
    }, 
    "mailingTube": true 
  } 
} 

Use cases

The following are typical scenarios that customers might encounter when integrating with our shipping APIs. Each use case is further illustrated using a call diagram, giving further clarity on the flow of data or requests and the parameters needed to make these calls.

Example 1

Get rates for shipping services

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

View larger image

Example 2

When you create a shipment, you can specify if you want:

• 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)  
• A return shipping label
• Pricing information
• A QR code 

The following image illustrates the minimum call set to get a label image.

View larger image

Example 3

Print a domestic shipping label with a return label

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

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

View larger image

Example 4

Get Canada Post charges for a shipment

You can make a call to get the Canada Post charges for your domestic, U.S., or international shipment.  

Add the call Get Shipment Price to any use case that starts with Create Shipment.

View larger image

Example 5

Ad hoc or batch call patterns

You can execute the label printing use cases using 1 of 2 call patterns:

• Ad hoc: One order 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’s transmitted.

The following diagram shows how to execute ad hoc and batch patterns.

View larger image

Example 6

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 get 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.

View larger image

Example 7

Transmit your shipments to receive a manifest

Unless you use only one group, it’s best to start with the synchronization call Get Groups to determine which groups contain shipments eligible for transmission.

The purpose of a group-id is to group several shipments together to include on the same manifest. You can execute the label printing use cases using one of two call patterns:

Performance limitations

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

• Don’t include more than 30 groups per manifest meaning no more than 30 group-ids in one Transmit Shipments request
• Don’t put more than 5,000 shipments in one group

System limitations

To avoid an error, don’t 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 10,000 shipments across multiple groups (error 9108 if exceeded)

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

View larger image

Example 8

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 JSON data, add an invocation of Get Manifest Details in the Transmit your shipments to receive a manifest process flow 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.

Best practices

The following workflow illustrates a scenario where Canada Post APIs have been integrated into an online store.

Select any link in the workflow for further details.

Testing and troubleshooting

Developers must decide when to expose an error message directly to the end-user versus implementing a mitigation strategy to prevent the error.

Common errors and how to fix them

Before troubleshooting, review our list of common errors and their codes. Each entry includes the specific HTTP status code and the recommended mitigation action.

Example: A 9112 error ("Service not available") may indicate a configuration problem. The mitigation is to check the available services for the selected origin or destination.

API error response structure

API error responses typically return a 400 Bad Request (for input validation errors) or a 500 Internal Server Error (for unexpected issues). The response body will contain a structured error object with the following key elements:

• code: The specific alphanumeric error code (for example, 9111).  
• message: A plain text description of the error.

Developer support

If you've implemented the recommended mitigation strategies and are still experiencing issues, please contact our developer support team.  

Related links

• Rating API overview
• Shipping API overview
• Manifest service