Release notes for Canada Post web services

Canada Post web services will change and evolve over time—new services or options will be added, old products retired, and bugs fixed. These modifications will necessitate a change in the version number of the web service. In some cases, upgrading to the new version will be optional, and mandatory in others. Advance notice of new features and versions will be provided by email. Old versions will be supported as long as feasible with ample notice if a version must be retired.

Web service categories

Our web services are grouped into several categories (e.g. Rating, Tracking, Contract Shipping, etc.). The version of a web service is indicated by a unique version name for all services within that category. Each category of services has been assigned an initial version to start and each category can version independently of the other categories. Your applications should use the same version of Canada Post web services when they are calling any web service from within the same category.

REST versioning

Version information is dynamically passed to web services in the HTTP header variables of Content-Type or Accept (see HTTP Header Variables). Version information is dynamically returned from web services in the media-type attribute of link elements.

For example, the header values for Rating web services are as follows:

HTTP Header Variable Value
Accept application/vnd.cpc.ship.rate-v4+xml
Content-Type application/vnd.cpc.ship.rate-v4+xml

Important: If, in the past, your REST requests to our web services have used */* in place of the Accept header, please note that as of
Sept. 21, 2013, we no longer support these requests. You must identify a value for your Accept and Content-type in your HTTP header.

SOAP Versioning

The version number for SOAP calls to web services is specified in the endpoint and the namespace. WSDLs will always document the most current web service versions.

Version status, history and release notes

Web Service Category Version Release Date Status Release Notes Schema Changes Planned Decommission Date
Rating 4 April 13, 2019

Current version

New element added for Get Rates request for more accurate delivery dates when shipping to Kahala Posts Group (KPG) countries.

View details
3 June 13, 2016

Supported

New adjustment code in Get Rates response to allow rates to be adjusted up or down for specific source and destination postal code combinations.

View details
3 Sept. 22, 2014

Supported

New elements added to Discover Services to allow search for postal services available to a given customer, contract, origin and/or destination postal code.

DOM.DT service code added to Get Rates for Delivered Tonight
View details
3 April 7, 2014 Supported New element in Get Rates request to enter a promotional discount code (for non-contract shipping only). When supplied, response includes the discount amount. View details
2 Jan. 5, 2013 Supported New comment element in Get Service response to indicate maximum amount of coverage for select U.S. and international services. View details
1 Nov. 21, 2011 Supported Initial release
Contract Shipping 8 June 13, 2016 Current version

The link rel="label" returned in the REST responses to Create Shipment and Get Shipment has been modified.

View details
8 April 18, 2016 Current version

For U.S. and international shipments, updates to Create Shipment:

  • To comply with international customs regulations.
  • To add support for some special characters in the name and company name fields.
  • To allow ability to select the maximum insurance coverage.

Additional formatting applied to phone number fields.

View details
8 Jan. 11, 2016 Current version

Updates to Create Shipment and other contract shipping web services to allow:

  • Approved supplier account vendors to pay by supplier account for their customers or pre-authorize payment on their behalf.
  • You to request that shipment price and shipment receipt be included in the response to Create Shipment.
  • Definition of your own unique customer request ID for each shipment and to search for shipments based on this ID.

View details
7 March 30, 2015 Supported

Request Shipment Refund - New web service to request a refund for a shipment that has been transmitted in error.

Update to contract shipping services to accommodate new web service.

View details
7 Oct. 25, 2014 Supported

Simplified COD payment process introduced:

  1. Send all COD shipments to a post office by selecting the Card for Pickup or Deliver to Post Office options.
  2. Recipients to pick up items and pay COD amount at the post office.
  3. Commercial customers to receive COD remittances electronically.

Removed: remittance labels, record of delivery labels and method of payment for COD shipments.

View details
6 June 23, 2014 Supported

New encoding element in Create Shipment that allows you to specify the output format for your shipping labels: PDF or ZPL II.

If you use the transmit-shipment element to identify a shipment where no manifest is required, you will now be able to print thermal labels.

New field that allows you to identify a shipment as continuous inbound freight (CIF). CIF shipments originate outside of Canada and are eligible for GST/HST exemptions.

View details
6 April 7, 2014 Supported

New Quick Ship option for contract shippers to produce a label that contains only the tracking barcode.

When shipping outside of Canada, recipient name or company is required.

SKU element has new character limitations.

More flexibility for how pickup and deposit location are specified.

View details
5 Jan. 13, 2014 Supported

Support for deposit site selection.

New customs data fields.

Valid characters in email addresses include plus sign (+)

View details
4 Sept. 23, 2013 Supported New transmit-shipment element in Create Shipment for customers who ship fewer than 50 parcels per day from multiple locations. View details
3 June 16, 2013 Supported Support for U.S. manifest addresses.
2 Jan. 5, 2013 Supported Updated customs value to accommodate larger dollar amounts.
1 Nov. 21, 2011 Supported Initial release
Customer Information 1 Nov. 21, 2011 Current version Initial release
Non-Contract Shipping 4 June 13, 2016 Current version

The link rel="label" returned in the REST responses to Create Shipment and Get Shipment has been modified.

View details
4 April 18, 2016 Current version

For U.S. and international shipments, updates to Create Non-Contract Shipment:

  • To comply with international customs regulations.
  • To add support for some special characters in the name and company name fields.
  • To allow ability to select the maximum insurance coverage.

Additional formatting applied to phone number fields.

View details
4 March 30, 2015 Current version

Request Non-Contract Shipment Refund - New web service to request a refund for a shipment /label created in error.

Update to non-contract shipping services to accommodate new web service.

View details
4 Oct. 25, 2014 Current version

Simplified COD payment process introduced:

  1. Send all COD shipments to a post office by selecting the Card for Pickup or Deliver to Post Office options.
  2. Recipients to pick up items and pay COD amount at the post office.
  3. Commercial customers to receive COD remittances electronically.

Removed: remittance labels, record of delivery labels and method of payment for COD shipments.

View details
3 April 7, 2014 Supported

<requested-shipping-point>changed from required to optional

When shipping outside of Canada, recipient name or company is required.

New structure added to support entry of a promotional discount code.

View details
2 Jan. 13, 2014 Supported

New field for the Postal Code of the Post Office where shipments will be deposited.

New customs data fields.

Valid characters in email addresses include plus sign (+)

View details
1 April 21, 2012 Supported Initial release
Tracking 2 April 16, 2016 Current REST version REST V2 created to fix the namespace for error messages
1 Nov. 21, 2011 Current SOAP version Initial release
Find a Post Office 1 Sept. 22, 2014 Current version New element in Get Nearest Post Office to allow requests for a list of Deliver to Post Office locations that accept Delivered Tonight parcels. View details
1 Nov. 21, 2011 Current version Initial release
Pickup 1 Spring 2015 Current version Initial release
Pickup Availability 1 Nov. 21, 2011 Current version Initial release
Returns (authorized) 2 February 12, 2023 Current version In Create Authorized Returns, there is now the ability to generate a QR code and to add an additional disposition readable bar code, by adding 3 fields to the Request and 2 fields to Response. View Details
2 February 8, 2020 Current version In Create Authorized Return, support for public label URL has been added. View details
2 June 13, 2016 Current version 3-inch x 5-inch return labels have been discontinued. For ZPL labels, use 4x6 labels. If you create 3x5 PDF labels, for an interim period they will still be accepted and converted to 4x6. View details
All versions June 23, 2014 Current version In Create Authorized Return, the weight element is optional rather than required. View details
2 June 23, 2014 Current version In Create Authorized Return, support for printing ZPL II return labels on 4”x6” thermal paper has been added. View details
2 Jan. 13, 2014 Supported

Valid characters in email addresses include plus sign (+).

After you create an authorized return label, you have 5 calendar days to retrieve it (using Get Artifact) instead of 2 days.

1 April 21, 2012 Supported Initial release
Returns
(open)
2 June 13, 2016 Current version 3-inch x 5-inch return labels have been discontinued. For ZPL labels, use 4x6 labels. If you create 3x5 PDF labels, for an interim period they will still be accepted and converted to 4x6. View details
2 June 23, 2014 Current version In Create Open Return Template, support for printing ZPL II return labels on 4”x6” thermal paper has been added. View details
2 Jan. 5, 2013 Current version Added a new field for customer input on the shipping label. View details
1 April 21, 2012 Supported Initial release
E-commerce Platforms 2 Jan. 11, 2016 Current version The response to the Get Merchant Registration Info web service includes a flag that indicates whether the merchant has a supplier account on file with Canada Post that can be used to pay for shipping transactions. View details
1 June 16, 2012 Supported Initial release
Service Info 2 April 7, 2014 Current version If there is no pending message, an HTTP error code of 200 (OK) is returned with an empty response, i.e., <info-messages></info-messages>. Previously, error code 404 (not found) was returned.
1 Sept. 23, 2013 Supported Initial release

Schema changes

Web Service Version Impacted Element Element Status Description of Change
Rating Category
Discover Services
(REST request)
3 Query parameters New

Optional

contract, origpc and destpc query parameters added to allow discovery of available postal services for a given contract, customer, and origin and destination postal codes.
Discover Services (SOAP request) 3 <customer-number> New

Optional

If provided in the request, the response will include all services accessible by the customer without a contract.
3 <contract-id> New

Optional

If the contract-id is provided, the response will also include restricted services accessible with that contract
3 <origin-postal-code> New

Optional

Postal code in format A9A or A9A9A9.

If origin-postal-code is provided, any service that is not valid for that origin will be filtered out, which is only applicable to the Delivered Tonight service. The origin can be your postal code (if mail is picked up by Canada Post) or the postal code of the location where you deposit your mail.

Delivered Tonight could be in the response when only contract-id is provided (i.e., it is available to the contract), but once origin and destination postal codes are provided, Delivered Tonight may no longer be applicable.

Both the origin and destination postal codes must be supplied to confirm Delivered Tonight is available for a given shipment. To determine if Delivered Tonight is an available service in your area, provide the origin postal code without a destination postal code.

3 <destination-postal-code> New

Optional

Postal code in format A9A or A9A9A9.

If destination-postal-code is provided, origin-postal-code must also be provided. Both are then used to confirm the availability of the Delivered Tonight service. The destination can be the recipient’s postal code or the postal code of the post office where the shipment is being sent (using the Deliver to Post Office option).
Get Rates (request) 4 <postal-code> New

Optional

The Postal Code field can be provided if the customer would like to receive a Guaranteed date for a Kahala Posts Group (KPG) country.

3 <promo-code> New

Optional

If you have a promotional discount code, enter it here. The discount amount will be returned in the response under the <adjustment> structure and the <adjustment-code> value PROMODISC.

Get Rates (response) 3 <adjustment-code> Changed

Added new code for:

SAADJ – Service area adjustment (rate adjustment up or down for specific source and destination postal code combinations)

Get Service (response) 2 <comment> New Coverage message stating the maximum amount of coverage included with this service (which can be none); only returned on a few U.S. and international services where additional coverage cannot be purchased.
Contract Shipping Category
Create Shipment (request) 8 <client-voice-number> Changed

Updated to support:

  • A plus sign (+), but only as the first character in the string.
  • Period (.), hyphen (-), open and close brackets, space, and x or p to indicate an extension.

8 <option-amount> Changed

On U.S. and international shipments, do not provide for COV option if you want the system to calculate the maximum allowable coverage (see option-qualifier-1 below).

8 <option-qualifier-1> Changed

Updated to allow use with the COV option on U.S. and international shipments. Use this field to indicate that the system can apply the maximum allowable coverage amount, which would equal the total value of your goods, up to the allowable maximum for product and country:

  • true = Use maximum allowable coverage; when used, there is no need to provide option-amount.
  • false (the default) = Use the amount of coverage as provided in option-amount.

8 <currency> Changed

Updated to validate the currency conforms to a valid ISO currency code.

8 <reason-for-export> Changed

GIF (for gift) is no longer a valid reason for export, as determined by the World Customs Organization for commercial shipments.

8 <other-reason> Changed

Updated to indicate this field must be a minimum of 4 characters (maximum 40 characters).

Create Shipment (request) 8 <customer-request-id> New

Optional

A unique ID that you can define for this shipment. Supplier Account vendors must use this field to provide a unique identifier for any shipment that is a pre-authorized payment request.

8 <provide-pricing-info> New

Optional
{true}
This element identifies that you want the shipment-price structure included in the response to this call. It will result in a larger payload but eliminates the need for a subsequent call to Get Shipment Price.
Only applicable to a shipment where transmit-shipment=true.
Only provide this parameter if you want pricing details in the response (i.e., do not provide when false).

8 <provide-receipt-info> New

Optional
{true}
This element identifies that you want the shipment-receipt structure included in the response to this call. It will result in a larger payload but eliminates the need for a subsequent call to Get Shipment Receipt.
Only applicable to a shipment where transmit-shipment=true that is paid by credit card or Supplier Account.
Only provide this parameter if you want receipt details in the response (i.e., do not provide when false).

8 <intended-method-of-payment> Changed

SupplierAccount added as method of payment. It indicates the payment will be through the Supplier Account specified in pre-authorized-payment or identified as default in the customer profile (only available to Supplier Account providers).
This element indicates your method of payment for a shipment where no manifest is required (transmit-shipments=true), or the intended method of payment otherwise (the actual method of payment being in the subsequent Transmit Shipments).

8 <promo-code> New

Optional
Promotional discount code. Note that a promotion code is only valid for a certain period and product.
Note: Promotion Code DEVPROTEST can be used to test this functionality in the sandbox environment. This promo code is only valid in the sandbox environment and for the following products:

  • Xpresspost (DOM.XP)
  • Xpresspost International (INT.XP)

8 <pre-authorized-payment> New

Optional
Supplier Account providers can pre-authorize payment using the Supplier Account of their customer.
Important: This functionality can only be used by Canada Post approved Supplier Account providers, and only on a shipment where no manifest is required.

8 <account-number> New

Required
The account number from which the amount will be withdrawn; will be used for reconciliation.

8 <auth-code> New

Required
(Character string – up to 16 characters)
The authorization code from the supplier; will be used for reconciliation.

8 <auth-timestamp> New

Required
The authorization date and time; will be used for reconciliation.

8 <charge-amount> New

Required
The amount authorized in Canadian dollars; must match the total charges that will be calculated.
Format 9999999.99 (leading zeroes not required).

Create Shipment (response) 8 rel="label" link Changed

The link rel="label" is now in the following format: (/ers was changed to /rs): href="https://XX/rs/artifact/11111111/5555555/0" media-type="application/pdf" index="0">

Create Shipment (response) 8 <customer-request-id> New

Your unique transaction ID, if you supplied it in your request.

8 <shipment-price> New

This structure will only be returned on a shipment where no manifest is required and where the provide-pricing-info element was set to true in the request.
It contains the same elements provided in the response to Get Shipment Price.

8 <shipment-receipt> New

This structure will only be returned on a shipment where no manifest is required and was paid for by credit card or Supplier Account.
It contains the same elements provided in the response to Get Shipment Receipt. Please note that the same dummy values are always returned in the sandbox environment (AA1111 for auth-code, for example).

Get Shipment (response) 8 rel="label" link Changed

The link rel="label" is now in the following format: (/ers was changed to /rs): href="https://XX/rs/artifact/11111111/5555555/0" media-type="application/pdf" index="0">

Get Shipment (response) 8 <customer-request-id> New

Your unique transaction ID, if you supplied it in your request.

Get Shipment Details (response) 8 <customer-request-id> New

Your unique transaction ID, if you supplied it in your request.

8 <adjustment-code> Changed

Added three new adjustment codes:

  • PROMODISC – Promotional discount (if the promo code is invalid or expired, the discount amount will show as zero under adjustment-cost)
  • PLATFMDISC: Discount for using an e-commerce platform
  • NEWREGDISC: Discount for joining the Developer Program

Get Shipment Receipt (response) 8 <shipment-cc-receipt> Changed

The XML element shipment-cc-receipt has been renamed shipment-receipt.

8 <supplier-account-receipt-details> New

This structure will be provided only if the shipment was paid by Supplier Account. It includes all the details to provide a receipt for a shipment paid by Supplier Account.
This structure is not returned in the sandbox environment

8 <merchant-name> New

Will have the value: "Canada Post".

8 <merchant-url> New

Will have the value: "www.canadapost.ca".

8 <auth-code> New

The authorization code received from the supplier.

8 <auth-timestamp> New

The date and time the supplier authorized the transaction.

8 <supplier-id> New

The supplier that authorized the transaction. Values are:

  • FP = FrancoTyp Postalia
  • NE = Neopost
  • PB = Pitney Bowes

8 <charge-amount> New

The total amount charged to the account.

8 <currency> New

The currency of the transaction; always CAD.

8 <transaction-type> New

Will have the value: "Sale".

Get Shipments (REST request) 8 Query parameters New

New query parameter added:

  • Search by customer-request-id

Get Shipments (SOAP request) 8 <provide-shipment-info> New

Reserved for internal use.

8 <customer-request-id> New

Optional
The customer-provided request ID of the shipment for which information is being requested.
Mutually exclusive with regular-shipping-parameters, no-manifest-shipping-parameters and tracking-pin.

Get Shipments (response) 8 <shipment-info> New

Reserved for internal use.

Transmit Shipments (request) 8 <customer-request-id> New

Reserved for future use

8 <method-of-payment> Changed

Added an additional method of payment:
SupplierAccount = the payment will be through the Supplier Account identified as default in the customer profile (only available to Supplier Account providers).

Get Manifest (response) 8 <customer-request-id> New

Reserved for future use.

Get Manifest Details (response) 8 <supplier-account-receipt-details> New

This structure will be provided if the manifest was paid for by Supplier Account in the Transmit Shipments request.
This structure is not returned in the sandbox environment.

8 <merchant-name> New

Will have the value: "Canada Post".

8 <merchant-url> New

Will have the value: "www.canadapost.ca".

8 <auth-code> New

The authorization code received from the supplier.

8 <auth-timestamp> New

The date and time the supplier authorized the transaction.

8 <supplier-id> New

The supplier that authorized the transaction. Values are:

  • FP = FrancoTyp Postalia
  • NE = Neopost
  • PB = Pitney Bowes

8 <charge-amount> New

The total amount charged to the account.

8 <currency> New

The currency of the transaction; always CAD.

8 <transaction-type> New

Will have the value: "Sale".

Create Shipment (response) 7 <link> New

The REST response will include the link rel="refund". This link is only returned on shipments where no manifest is required.

Get Shipment Details (response) 7 <refund-request-info> New

This structure is present only if a refund request was submitted for this shipment.

7 <service-ticket-date> New

Date when the refund request was submitted.

7 <service-ticket-id> New

Service ticket number assigned to the refund request. Please use this number in any communications with Canada Post about the refund request.

Get Shipments (request) 7 <tracking-pin> New

For SOAP, a new tracking PIN element has been added. For REST, a tracking PIN query parameter has been added.

Create Shipment (request) 7 <option-code> Changed

If you select Collect on Delivery (COD), specify Card for Pickup (HFP) or Deliver to Post Office (D2PO). This is to facilitate the collection of COD funds at a post office. If not specified, the system will default to HFP.

7 <cod-remittance> Removed

Removed in v7. Will be ignored if provided in previous versions.

7 <option-qualifier-2> Changed

Method of payment for COD shipments no longer required.

Create Shipment (response) 7 <link> Changed

The REST response will no longer include the following links:

  • codRemittanceLabel
  • codRecordOfDelivery
  • codRemittanceReturnLabel

7 <artifact> Changed

The SOAP response will no longer include an artifact element containing:

  • codRemittanceLabel and
  • codRemittanceReturnLabel

Get Shipment Details (response) 7 <cod-remittance> Removed

No longer provided. COD remittances are now handled electronically.

Create Shipment (request) 6 <encoding> New

{PDF, ZPL}

Use this field to specify the output format for your shipping label: PDF or ZPL II. If not provided, PDF will be selected by default.

If you choose ZPL, the response from a Get Artifact call returns ZPL II programming language commands. You will need to stream the commands to your thermal printer. Please note that in SOAP, the commands are Base64 encoded.

ZPL is only available on thermal paper so <output-format> must be 4x6.
6 <cif-shipment> New

{true}

If you have shipments that originate outside of Canada, but are being delivered directly to a Canada Post plant, use this element to identify these shipments as continuous inbound freight (CIF). This option allows you to be eligible for Canadian sales tax exemptions. You will need to provide Canada Post with documentation that shows proof of origin, such as a Canadian customs document or bill of lading.

Only provide this parameter when the shipment is CIF (i.e. do not provide when false).

6 <quickship-label-requested> New

{true}

Use this element if you already have a domestic parcel with the recipient’s name and address on it, but you want to create an additional label to affix to the parcel for tracking purposes. For billing purposes, you must also provide the <country-code> and the <postal-zip-code> fields in the destination structure.

6 <requested-shipping-point> Changed

Can be used to specify either the postal code of your pickup location or the postal code of your deposit site.

Note: In a future release it will become mandatory to explicitly identify whether your shipment is picked up by Canada Post (by providing both this indicator and <cpc-pickup-indicator>) or deposited at a Canada Post site (by providing shipping-point-id).

6 <cpc-pickup-indicator> Changed

Changed from conditionally required to optional.

Note: In a future release, if your shipment is picked up, it will become mandatory to provide both this field and <requested-shipping-point>.

6 <shipping-point-id> Changed Mutually exclusive with <requested-shipping-point>.
6 <name> Changed

When shipping outside of Canada, in the <destination> structure, at least one of <name> or <company> is required to comply with international customs regulations.

Not required when <quickship-label-requested> is true.

6 <company> Changed

Changed from optional to conditionally required.

When shipping outside of Canada, in the <destination> structure, at least one of <name> or <company> is required to comply with international customs regulations.

6 <address-line-1> Changed

Changed from optional to conditionally required.

Not required when <quickship-label-requested> is true; mandatory otherwise.

6 <sku> Changed

Changed from 44-character maximum to 15-character maximum.

Note: Versions 1 through 5 of contract shipping will allow up to 44 characters, but data will be truncated at 15 characters (to comply with customs regulations).

Get Shipment Details (response) 6 <quickship-label-requested> New

{true}

Returned if provided in the Create Shipment request.

Transmit Shipments 6 <requested-shipping-point> Changed

Can be used to specify either the postal code of your pickup location or the postal code of your deposit site.

Note: In a future release it will become mandatory to explicitly identify whether your shipment is picked up by Canada Post (by providing both this indicator and cpc-pickup-indicator) or deposited at a Canada Post site (by providing shipping-point-id).

6 <cpc-pickup-indicator> Changed Changed from conditionally required to optional.
6 <shipping-point-id> Changed Mutually exclusive with <requested-shipping-point>.
Create Shipment (request) 5 <requested-shipping-point> Changed

Changed from ‘Required’ to ‘Conditionally required’.

Postal Code of location where shipments are picked up by Canada Post.

Must only be provided when <cpc-pickup-indicator>=true.

Mutually exclusive with <shipping-point-id>.

5 <cpc-pickup-indicator> New

Conditionally required.

If your shipments are picked up by Canada Post (or a 3rd party), set this indicator to true and provide the Postal Code of the pickup location in <requested-shipping-point>.

Mutually exclusive with <shipping-point-id> but one of the two must be provided.

5 <shipping-point-id> New

Conditionally required.

If you deposit your shipments at a Canada Post site, provide the site number of that location. (Look up the number using Find a Deposit Location.) This information is used for pricing.

Mutually exclusive with cpc-pickup-indicator but one of the two must be provided.

5 <duties-and-taxes-prepaid> New Reserved for future use.
5 <certificate-number> New

Optional.

If required by customs at the destination, the number of the government/agency certificate or permit.

5 <licence-number> New

Optional.

If required by customs at the destination, the number of the government/agency import or export licence.

5 <invoice-number> New

Optional.

If required by customs at the destination, the commercial invoice number.

5 <additional-customs-info> Removed

Optional.

New fields have been introduced to replace this information.

5 <customs-unit-of-measure> New

Optional.

The three-character ISO code that identifies the unit of measure for your item.

4 <group-id> Changed

Changed from ‘Required’ to ‘Conditionally Required’.

It is mandatory unless transmit-shipment is provided, in which case group-id must not be provided.

4 <transmit-shipment> New

Optional.

{true}
When true, the system will immediately transmit the shipment instead of waiting for a subsequent Transmit Shipments action. No manifest is required for shipping.

Create Shipment (response) 4 rel=“receipt” New

This link is used to access a credit card receipt that was generated by the Create Shipment process when <transmit-shipment>=true.

Invokes the Get Shipment Receipt web service.

Get Shipment Details (response) 5 <final-shipping-point> Changed If you specified a shipping-point-id element in your Create Shipment request, this will be the Postal Code of the deposit location you chose.
5 <shipping-point-id> This is the Canada Post site number of the final shipping point.
5 <cpc-pickup-indicator> Returned if you specified that your shipments are picked up by Canada Post at your site. Only supplied when true.
5 <duties-and-taxes-prepaid> New Reserved for future use.
5 <certificate-number> New The number of the government/agency certificate or permit for customs purposes.
5 <licence-number> New The number of the government/agency import or export licence for customs purposes.
5 <invoice-number> New The commercial invoice number for customs purposes.
5 <additional-customs-info> Removed New fields have been introduced to replace this information.
5 <customs-unit-of-measure> New The three-character ISO code that identifies the unit of measure for your item.
4 <po-number> New The Canada Post Purchase Order number; only applicable and returned on a shipment where <transmit-shipment>=true.
4 <transmit-shipment> New This field is identical to the corresponding element in the request to Create Shipment (mutually exclusive with group-id).
Get Shipments (request) 4 n/a New New endpoint introduced to retrieve a list of shipments where <transmit-shipment>=true: GET https://XX/rs/{mailed by customer}/{mobo}/shipment?noManifest=true&date=YYYYMMDD&limit={number}
Get Shipment Receipt (NEW) 4 n/a n/a

Applicable only to credit card shipments where
<transmit-shipment>=true.

Obtain credit card receipt information as follows:

  • REST: Invoke rel=‘receipt’ link from a prior Create Shipment call or Get Shipment response where <transmit-shipment>=true.
  • SOAP: Use the data in the response from a call to Get Shipment Receipt to create a receipt.
Transmit Shipments (request) 5 <requested-shipping-point> Changed

Changed from ‘Required’ to ‘Conditionally required’.

Postal Code of the location where shipments are picked up by Canada Post.

Must only be provided when <cpc-pickup-indicator>=true.

Mutually exclusive with <shipping-point-id>.

5 <cpc-pickup-indicator> New

Conditionally required.

If your mail is picked up by Canada Post (or a third party), set this indicator to true and provide the Postal Code of the pickup location in <requested-shipping-point>.

Mutually exclusive with <shipping-point-id> but one of the two must be provided.

5 <shipping-point-id> New

Conditionally required.

If you deposit your shipments at a Canada Post site, provide the site number of that location. (Look up the number using Find a Deposit Location.) This information is used for pricing.

Mutually exclusive with cpc-pickup-indicator but one of the two must be provided.

Get Manifest Details (response) 5 <cpc-pickup-indicator> New Returned if you specified that your mail is picked up by Canada Post at your site. Only supplied when true.
Non-Contract Shipping Category
Create Non-Contract Shipment (request) 4 <client-voice-number> Changed

Updated to support:

  • A plus sign (+), but only as the first character in the string.
  • Period (.), hyphen (-), open and close brackets, space, and x or p to indicate an extension.

4 <option-amount> Changed

On U.S. and international shipments, do not provide for COV option if you want the system to calculate the maximum allowable coverage (see option-qualifier-1 below).

4 <option-qualifier-1> Changed

Updated to allow use with the COV option on U.S. and international shipments. Use this field to indicate that the system can apply the maximum allowable coverage amount, which would equal the total value of your goods, up to the allowable maximum for product and country:

  • true = Use maximum allowable coverage; when used, there is no need to provide option-amount.
  • false (the default) = Use the amount of coverage as provided in option-amount.

4 <currency> Changed

Updated to validate the currency conforms to a valid ISO currency code.

4 <reason-for-export> Changed

GIF (for gift) is no longer a valid reason for export, as determined by the World Customs Organization for commercial shipments.

4 <other-reason> Changed

Updated to indicate this field must be a minimum of 4 characters (maximum 40 characters).

Create Non-Contract Shipment (response) 4 rel="label" link Changed

The link rel="label" is now in the following format: (/ers was changed to /rs): href="https://XX/rs/artifact/11111111/5555555/0" media-type="application/pdf" index="0">

Create Non-Contract Shipment (response) 4 <link> Changed

The REST response will include the link rel="refund". This link is only returned on shipments where no manifest is required.

Get Non-Contract Shipment Details (response) 4 <refund-request-info> New

This structure is present only if a refund request was submitted for this shipment.

4 <service-ticket-date> New

Date when the refund request was submitted.

4 <service-ticket-id> New

Service ticket ID number assigned to the refund request. Please use this number in any communications with Canada Post about the refund request.

Get Non-Contract Shipments (request) 4 <tracking-pin> New

For SOAP, a new tracking PIN element has been added. For REST, a tracking PIN query parameter has been added.

Create Non-Contract Shipment (request) 4 <option-code> Changed

If you select Collect on Delivery (COD), specify Card for Pickup (HFP) or Deliver to Post Office (D2PO). This is to facilitate the collection of COD funds at a post office. If not specified, the system will default to HFP.

4 <cod-remittance> Removed Removed in v4. Will be ignored if provided in previous versions.
4 <option-qualifier-2> Changed

Method of payment for COD shipments no longer required.

Create Non-Contract Shipment (response) 4 <link> Changed

The REST response will no longer include the following link:

  • codRemittanceLabel

4 <artifact> Changed

The artifact element in the SOAP response will no longer contain:

  • codRemittanceLabel and
  • codRemittanceReturnLabel

Get Non-Contract Shipment Details (response) 4 <cod-remittance> Removed

No longer provided. COD remittances are now handled electronically.

Create Non-Contract Shipment (request) 3 <requested-shipping-point> Changed

Changed from required to optional.

Required if:

  • Your shipment is not picked up by Canada Post at the postal code specified in the sender structure below (i.e., it is picked up at another location), or
  • You deposit your shipment at a Canada Post location, in which case you must enter the postal code of that location.

3 <name> Changed When shipping outside of Canada, in the <destination> structure, at least one of <name> or <company> is required to comply with international customs regulations.
3 <company> Changed

Changed from optional to conditionally required.

When shipping outside of Canada, in the <destination> structure, at least one of <name> or <company> is required to comply with international customs regulations.

3 <sku> Changed

Changed from 44-character maximum to 15-character maximum.

Note: Versions 1 through 2 of non-contract shipping will allow up to 44 characters, but data will be truncated at 15 characters (to comply with customs regulations).

3 <settlement-info> New

Optional

New structure under <delivery-spec> that contains the new <promo-code> element.

3 <promo-code> New

Optional

Character string up to 10 characters.

Promotional discount code.

Converted to upper-case

Get Non-Contract Shipment Details (response) 3 <settlement-info> New New structure under <delivery-spec>. Contains the new <promo-code> element.
3 <promo-code> New Returned if a valid <promo-code> is provided in the request.
Create Non-Contract Shipment (request) 2 <requested-shipping-point> New

Required

Postal Code of the location at the origin. It is used to determine the nearest postal facility, which is used for pricing.

2 <duties-and-taxes-prepaid> New Reserved for future use.
2 <certificate-number> New

Optional

If required by customs at the destination, the number of the government/agency certificate or permit.

2 <licence-number> New

Optional

If required by customs at the destination, the number of the government/agency import or export licence.

2 <invoice-number> New

Optional

If required by customs at the destination, the commercial invoice number.

2 <additional-customs-info> Removed New fields have been introduced to replace this information.
2 <customs-unit-of-measure> New

Optional

The three-character ISO code that identifies the unit of measure for your item.

Get Non-Contract Shipment Details (response) 2 <final-shipping-point> Changed If you specified a shipping-point-id element in your Create Non-Contract Shipment request, this will be the Postal Code of the deposit location you chose.
2 <duties-and-taxes-prepaid> New Reserved for future use.
2 <certificate-number> New The number of the government/agency certificate or permit for customs purposes.
2 <licence-number> New The number of the government/agency import or export licence for customs purposes.
2 <invoice-number> New The commercial invoice number for customs purposes.
2 <additional-customs-info> Removed New fields have been introduced to replace this information.
2 <customs-unit-of-measure> New The three-character ISO code that identifies the unit of measure for your item.
Find a Post Office
Get Nearest Post Office 1 <tonight> New

true | false

True indicates that you want a list of post offices that accept Deliver to Post Office parcels and can also be used for the Delivered Tonight service (i.e. those with extended hours of service). Cannot be true when d2po is false.
Returns (open)
Create Open Return Template (request) 2 <output-format> Changed

Modified to remove the 3x5 label format in June 2016 (but for an interim period will still be accepted and converted to 4x6 for PDF labels).

Create Open Return Template (request) 2 <encoding> Changed

Modified to include ability to print ZPL II return labels on 4x6 thermal paper.

{PDF, ZPL}

Use this field to specify the output format for your return label: PDF or ZPL II. If not provided, PDF will be selected by default.

If you choose ZPL, the response from a Get Artifact call returns ZPL II programming language commands. You will need to stream the commands to your thermal printer. Please note that in SOAP, the commands are Base64 encoded.

ZPL is only available on thermal paper, but 3x5 labels are not yet available. The <output-format> must therefore be 4x6.

Create Open Return Template 2 <customer-input-type> New Create return labels that contain a spot for your customers to enter data. This field only applies to 4”x6” and 8.5”x11” label sizes. It will be ignored for 3”x5” labels.

Valid values are as follows:
Code Label Description
INVOICE Invoice No / No de facture
ITEM Item No / No d’article
ORDER Order No / No de commande
PART Part No / No de pièce
PO PO No / No de bon de comm.
RETURN Return No / No de retour
RSA RSA No / No d’ARM
SERIAL Serial No / No de série
SKU SKU No / No UGS
Returns (authorized)
Create authorized return (request) 2 <create-public-key> New Optional
{true}
If flag is present and set to “true”, it will enable a generation of public URL to retrieve a PDF version of shipping label and inclusion of this URL along with expiry date in service response.
2 create-qr-code New

(true|false)

If flag is present and set to “true”, AND create-public-key is also true, the QR code encoding of the public URL is automatically generated and returned in the response.

2 customer-barcode New

(16 alphanumeric)

Value of the barcode.

If present, the barcode will be rendered in the customer info area of the authorized return label (usually at the bottom).

2 customer-barcode-type New

(LINEAR|2D)

Type of the barcode. Mandatory if customer-barcode is specified.

2 <output-format> Changed Modified to remove the 3x5 label format in June 2016 (but for an interim period will still be accepted and converted to 4x6 for PDF labels).
2 <weight> Changed Changed from required to optional.
2 <parcel-characteristics> Changed Changed from required to optional.
2 <encoding> Changed

Modified to include ability to print ZPL II return labels on 4x6 thermal paper.

{PDF, ZPL}

Use this field to specify the output format for your return label: PDF or ZPL II. If not provided, PDF will be selected by default.

If you choose ZPL, the response from a Get Artifact call returns ZPL II programming language commands. You will need to stream the commands to your thermal printer. Please note that in SOAP, the commands are Base64 encoded.

ZPL is only available on thermal paper, but 3x5 labels are not yet available. The <output-format> must therefore be 4x6.

Create authorized return (response) 2 <public-key-info> New New structure under <authorized-return-info> that contains the new <expiry-date> and <url> elements
2 <expiry-date> New The expiry date of label public URL.
2 <url> New Actual URL to retrieve PDF version of the label.
2 customer-barcode New The barcode value that is specified in the request (if provided).
2 qr-code New The Base64 encoding of the actual image of the QR code that represents the public URL (if create-qr-code and create-public-key are both present in the request and set to true).
E-commerce platforms
Get Merchant Registration Info (response) 2 < has-default-supplier-account> New

{true|false}

Indicates whether the merchant has a default supplier account on file with Canada Post that can be used for shipping transactions.

If the value is true, the merchant can perform shipping transactions using that method of payment.

If this value and has-default-credit-card are false, the merchant cannot perform shipping transactions without a contract.

Note: Supplier Account as a method of payment is only available to suppliers.