create-authorized-return-request

complex

required

The top level XML element for the request input information.

mailed-by

simple

required

(1-10 digit numeric)

The 10-digit customer number of the mailed-by customer.

If the number provided has fewer than 10 digits, the system will add leading zeros.

mobo

simple

optional

(1-10 digit numeric)

The 10-digit customer number of the mailed-on-behalf-of customer.

If this element is missing, it will default to the mailed-by customer number.

If the number provided has fewer than 10 digits, the system will add leading zeros.

locale

simple

optional

Indicates your language preference for receiving error messages.

EN = English
FR = French

If no value is provided, the default language is English.

authorized-return

complex

required

This structure provides a description of the return request details, including receiver, service-code, returner, parcel-characteristics and references.

create-public-key

Simple

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. That functionality can be leveraged if shipper prefers to send customer a link to the label rather than a label as attachment.
Also, shipper can send to customer QR code encoding public URL, that would allow customer to use QR code for printing out label in any CPC retail location.
Expiry date indicates when such link to retrieve the label will no longer be accessible.

create-qr-code

Simple

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

customer-barcode

Simple

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

customer-barcode-type

Simple

(LINEAR|2D)
Type of the barcode. Mandatory if customer-barcode is specified.

box-free

Simple

(true|false)

if flag is present and set to ‘true, “Box-free / Sans emballage” verbiage is added on the image containing the QR code and green colored QR code is generated. Note: There are eligibility requirements for box-free returns. If items are not eligible, they will not be accepted as a box-free return at the post office. See the Parcel Services Customer Guide for more information.

service-code

simple

required

(Character string – up to 32 alphanumeric)

Return labels can only be created if the shipment originates in Canada and is destined for delivery in Canada.

This is the Canada Post delivery service used for shipping the item.

returner

complex

required

This structure contains data about the sender that will appear in the “From” address of the label. Blank fields will be removed in the address formatting.

name

simple

required

(44 alphanumeric)

Contact name of the corresponding returner.

company

simple

optional

(44 alphanumeric)

Company name of the corresponding returner.

domestic-address

complex

required

This structure contains the address data about the returner of the shipment. Blank fields will be removed in address fields for formatting the labels.

address-line-1

simple

required

(44 alphanumeric)

address-line-2

simple

optional

(44 alphanumeric)

city

simple

required

(40 alphanumeric)

province

simple

required

(2 characters)

postal-code

simple

required

(6-digit code in Canadian Postal Code pattern: A9A9A9)

receiver

complex

required

This structure contains data about the destination and will appear in the “To” address of the label. Blank fields will be removed in the address formatting.

name

simple

required

(44 alphanumeric)

Contact name of the corresponding receiver.

company

simple

optional

(44 alphanumeric)

Company name of the corresponding receiver.

email

simple

optional

(60 characters - must be a valid email pattern)

For future use.

receiver-voice-number

simple

optional

(Character String – up to 25 characters)

Phone number of the receiver.

Will not appear on shipping label.

domestic-address

complex

required

Required if the corresponding parent XML element “receiver” exists.

This structure contains the address data about the receiver of the shipment. Blank fields will be removed in address fields for formatting the labels.

address-line-1

simple

required

(44 alphanumeric)

address-line-2

simple

optional

(44 alphanumeric)

city

simple

required

(40 alphanumeric)

province

simple

required

(2 characters)

postal-code

simple

required

(6-digit code in Canadian Postal Code pattern: A9A9A9)

parcel-characteristics

complex

optional

This structure contains the information about the physical characteristics of the parcel.

weight

simple

optional

(Numeric field of pattern 3.3 e.g. 999.999)

Total package weight in kg.

dimensions

complex

optional

This structure contains information specifying the dimensions of a parcel.

length

simple

conditionally
required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Required if the corresponding parent XML element “dimensions” exists.

Length of parcel in cm.

If length is specified, a more accurate price can be derived.

width

simple

conditionally
required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Required if the corresponding parent XML element “dimensions” exists.

Width of parcel in cm.

If width is specified, a more accurate price can be derived.

height

simple

conditionally
required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)

Required if the corresponding parent XML element “dimensions” exists.

Height of parcel in cm.

If height is specified, a more accurate price can be derived.

print-preferences

complex

optional

This structure contains print preferences for the labels.

output-format

simple

optional

(7 alphanumeric)

Valid values are:
- 8.5x11
- 4x6

If this element is not present, 8.5x11 is the default.

encoding

simple

optional

{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 will include a file containing Base64 encoded data. Decode the file to get the ZPL II printer commands. You will then need to either code a solution or use an application to stream the commands directly to a thermal printer.

For ZPL II labels, your printer must support truncation. Use our sample code to test your printer’s ability to truncate text.

ZPL is only available on thermal paper. The <output-format> must therefore be 4x6.

show-packing-instructions

simple

optional

{true, false} Defaults to True

This element indicates whether packing instructions are to be rendered on the label.

settlement-info

complex

required

This structure is analogous to the structure from Create Shipment; however, here the contents are optional and recommended to be omitted.

paid-by-customer

simple

optional

(10-digit numeric)

For future use.

contract-id

simple

optional

(10-digit numeric)

For future use.

references

complex

optional

This structure contains reference fields that you can assign. These alternate (possibly unique) identification numbers are assigned to the return, and can be used for tracking or for any other purpose you deem useful.

customer-ref-1

simple

optional

(Character string – up to 35 characters)

This is a user-defined value available for use by your applications. The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

customer-ref-2

simple

optional

(Character string- up to 35 characters)

This is a user-defined value available for use by your applications. The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

notifications

complex

optional

This structure holds email notification settings for receiving parcel tracking information.

notification

complex

mandatory

If the notifications structure is present, at least one notification instance is required and up to 4 are allowed. This structure holds one email address and the kinds of notifications to be sent to the email address.

email

simple

mandatory

(Email string up to 60 characters)

Email address to receive automatic tracking updates.

Must be a valid email address, i.e., pattern of (['_A-Za-z0-9\-\+])(\.['_A-Za-z0-9\-\+])@([A-Za-z0-9-])(\.[A-Za-z0-9-])(\.[A-Za-z]{2,})

If the notification structure is present, the email address element must be provided.

on-shipment

simple

mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all shipment related tracking updates will be sent to the email addressed.

on-exception

simple

mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all exception related tracking updates will be sent to the email addressed.

on-delivery

simple

mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all delivery related tracking updates will be sent to the email addressed.

email-subject

simple

optional

{tracking,customer-ref-1,customer-ref-2}

Email subject lines have the following general forms depending on type of notification:

• Ship Notification for Item / Avis d’expédition pour l’article :
• Exception Notification for Item / Avis d’exception pour l’article :
• Delivery Notification for Item / Avis de livraison pour l’article :

The value following the colon defaults to “TRACKING” and the Canada Post tracking number. Or you can set it to “REFERENCE” and one of the customer reference numbers.

create-authorized-return-response

complex

The top level XML element for the response.

It will either contain the results of a successful completion or the error message structure.

authorized-return

complex

The XML structure that contains the information about the authorized return.

public-key-info

Complex

This structure represents data pertaining to label public URL – the URL to retrieve a PDF version of shipping label along with expiry date of the URL.

expiry-date

Simple

The expiry date of label public URL.

url

Simple

Actual URL to retrieve PDF version of the label in format
http://est.canadapost.ca/esto/app/bypass/label?key={generated_key}

qr-code

simple

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

tracking-pin

simple

The tracking PIN for the shipment. It can be used as input to other web service calls such as Get Tracking Details.

customer-barcode

simple

The barcode value that is specified in the request (if provided).

artifacts

complex

Structure containing all documents/labels produced for the authorized return.

artifact

complex

Structure containing a single document/label produced for the authorized return.

type

attribute

Attribute of artifact.

This indicates the purpose of the document and the type of information that will be retrieved—in this case "returnLabel".

artifact-id

simple

Numeric identifier for the specific document that was generated for the authorized return.

Note: After you create an authorized return, you have five calendar days to retrieve the return label before the artifact expires.

9191

ZPL is a language for thermal printers. You can therefore only use it with 4x6 thermal paper.

9192

3x5 return labels are not available anymore. Please use 4x6 on thermal printers.

9208

Public labels are only available in 8.5x11 PDF format.