Returns

Code Samples for Returns: Java (.zip) | PHP (.zip) | C# (.zip)

Create Authorized Return – REST

Summary

Name: Create Authorized Return
Reason to Call: To create an authorized return that allows you to retrieve and print a return shipping label that can be sent (either physically or electronically) to a shopper.
Input: Shipment input information including return address (both sender and receiver) and parcel characteristics (e.g. dimensions, weight)
Output: Pointers to artifact to allow label to be printed.
Error Example: Errors in address or parcel characteristics.
Typical Next Call: Get Artifact to retrieve the return shipping label.
Version history: Release notes
Create Authorized Return – Summary of Service

Create Authorized Return – Summary of Service

Request Details

Request – Structure for Create Authorized Return

Endpoint

POST https://XX/rs/{mailed by customer}/{mobo}/authorizedreturn

Replace... With...

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{mailed by customer}

your customer number

{mobo}

the mailed on behalf of customer number or repeat your customer number

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.authreturn-v2+xml (Note: */* in place of the header value will return an error)

Content-Type

application/vnd.cpc.authreturn-v2+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

Body

<?xml version="1.0" encoding="utf-8"?>
<authorized-return xmlns=”http://www.canadapost.ca/ws/authreturn-v2”>
xxx
</authorized-return>

Request – Elements

This table describes the XML elements that make up the input to this service. The hierarchical structure of the XML inputs is shown in the Request - XML Diagram.

Create Authorized Return – Request Elements
Element Name Type Required / Optional Description

authorized-return

Complex

Required

This is the overall XML structure for the request input information. This structure provides a description of the return request details, including receiver, service-code, returner, parcel-characteristics and references.

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.

Service-Code Description
DOM.RP Regular Parcel
DOM.EP Expedited Parcel
DOM.XP Xpresspost
DOM.PC Priority

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.

Note: The 3x5 format was discontinued in June 2016, but for an interim period will still be accepted and converted to 4x6.

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 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,5})

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.

Request – XML Diagram

Create Authorized Return – Structure of the XML Request
Create Authorized Return – Structure of the XML Request

Response Details

Response – Elements

The following table describes the XML fields in the response. For a detailed view of the hierarchy of the response, see the diagram below.

Create Authorized Return – Response Elements
Element Name Type Description

authorized-return

Complex

This is the top level XML element for the response.
This is the XML structure that contains the information about the created authorized return.

tracking-pin

Simple

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

links

Complex

This structure represents a list of links to information relating to the shipment that was created.

return-link

Complex

The links structure contains a single return-link element.
e.g.

<link href=”https://XX/ers/artifact/12346789/9876554/01
rel=”returnLabel" index=”1”
media-type=”application/png”/>

This link contains no sub-elements and has three attributes as follows:

  1. href. String. This is the endpoint that can be used to call the Get Artifact service to retrieve the label for the authorized return just created.

  1. rel. String. In the generic use of the link element, this indicates the purpose of the link and the type of information that will be retrieved. In the case of this service, there will only be a single return-link element, and it will have a rel=“returnLabel” value indicating that href can be used to call Get Artifact to retrieve the return label. There are no other types of links associated with this service.

  1. media-type. The media-type attribute indicates the format of the graphics file (e.g. PDF or ZPL).

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

Response – XML Diagram

Create Authorized Return – Structure of the XML Response

Create Authorized Return – Structure of the XML Response

Response – Possible Error Responses

In the case of an application error, an HTTP 400 level status code error response will be generated and the XML body will have an error message structure rather than the success response. For more information, see HTTP status codes.

Code

Description

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.

Examples

Sample REST XML Request – Create Authorized Return

<authorized-return>
<service-code>DOM.EP</service-code>
<returner>
<name>Jane Doe</name>
<company>Capsule Corp.</company>
<domestic-address>
<address-line-1>2701 Return Avenue</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1A0B1</postal-code>
</domestic-address>
</returner>
<receiver>
<name>John Doe</name>
<company>Canada Post Corporation</company>
<domestic-address>
<address-line-1>2701 Riverside Drive</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1A0B1</postal-code>
</domestic-address>
</receiver>
<parcel-characteristics>
<weight>15</weight>
</parcel-characteristics>
<print-preferences>
<output-format>8.5x11</output-format>
</print-preferences>
<settlement-info></settlement-info>
</authorized-return>

Sample REST XML Response – Create Authorized Return

<authorized-return-info>
<tracking-pin>12345678901234</tracking-pin>
<links>
<linkhref="https://ct.soa-gw.canadapost.ca/ers/artifact/76108cb5192002d5/21238/0"rel="returnLabel"media-type="application/pdf"index="0"></link>
</links>
</authorized-return-info>