Current version

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

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.

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.

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

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.

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.

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.

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.

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.

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.

Support for deposit site selection.

New customs data fields.

Valid characters in email addresses include plus sign (+)

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

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.

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.

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.

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

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 (+)

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.

Optional

Optional

Optional

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.

Optional

Postal code in format A9A or A9A9A9.

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.

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.

Added new code for:

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

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.

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

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.

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

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

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

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.

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

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

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

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)

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.

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

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

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

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

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">

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

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.

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

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">

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

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

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

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

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

Will have the value: "Canada Post".

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

The authorization code received from the supplier.

The date and time the supplier authorized the transaction.

The supplier that authorized the transaction. Values are:

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

The total amount charged to the account.

The currency of the transaction; always CAD.

Will have the value: "Sale".

New query parameter added:

• Search by customer-request-id

Reserved for internal use.

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.

Reserved for internal use.

Reserved for future use

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

Reserved for future use.

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.

Will have the value: "Canada Post".

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

The authorization code received from the supplier.

The date and time the supplier authorized the transaction.

The supplier that authorized the transaction. Values are:

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

The total amount charged to the account.

The currency of the transaction; always CAD.

Will have the value: "Sale".

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

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

Date when the refund request was submitted.

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

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

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.

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

Method of payment for COD shipments no longer required.

The REST response will no longer include the following links:

• codRemittanceLabel
• codRecordOfDelivery
• codRemittanceReturnLabel

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

• codRemittanceLabel and
• codRemittanceReturnLabel

No longer provided. COD remittances are now handled electronically.

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

{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).

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

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

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

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.

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.

Changed from optional to conditionally required.

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

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

{true}

Returned if provided in the Create Shipment request.

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

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

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.

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.

Optional.

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

Optional.

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

Optional.

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

Optional.

New fields have been introduced to replace this information.

Optional.

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

Changed from ‘Required’ to ‘Conditionally Required’.

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

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.

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.

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.

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

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.

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.

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.

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

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.

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

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

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

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">

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

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

Date when the refund request was submitted.

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

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

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.

Method of payment for COD shipments no longer required.

The REST response will no longer include the following link:

• codRemittanceLabel

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

• codRemittanceLabel and
• codRemittanceReturnLabel

No longer provided. COD remittances are now handled electronically.

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.

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.

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

Optional

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

Optional

Character string up to 10 characters.

Promotional discount code.

Converted to upper-case

Required

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

Optional

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

Optional

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

Optional

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

Optional

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

true | false

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

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.

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

(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).

(LINEAR|2D)

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

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.

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