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

Accept

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

Content-Type

application/vnd.cpc.openreturn-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

open-return

Complex

Required

This is the overall XML structure for the request input information.

max-number-of-artifacts

Simple

Required

Indicates the maximum number of artifacts (return labels) you can generate and retrieve using this template. Must be numeric in the range of 1 - 100,000.

service-code

Simple

Required

(32 alphanumeric)

The returns service is appropriate for domestic returns only.

receiver

Complex

Required

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

name

Simple

Required

(44 characters)

company

Simple

Optional

(44 characters)

domestic-address

Complex

Required

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

address-line-1

Simple

Required

(44 characters)
Address line 1 of receiver.

address-line-2

Simple

Optional

(44 characters)
Address line 2 of receiver.

city

Simple

Required

(40 characters)
City of receiver.

province

Simple

Required

(2 characters)
Province of the receiver.

postal-code

Simple

Required

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

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}
This element indicates whether packing instructions are to be rendered on the label.
If this element is not present, the default value is false.

customer-input-type

Simple

Optional

(20 alphanumeric)

Use this element to create return labels that contain a spot for your customers to enter data such as a part number, SKU number, etc.

This field only applies to 4x6 and 8.5x11 label sizes.

Valid values are as follows:

settlement-info

Complex

Required

This structure contains your regular outgoing parcel contract number for verification purposes.

contract-id

Simple

Required

(10-digit numeric)
Required to use the Open Returns service. Only Canada Post commercial customers with a volume-based agreement can use the service.

open-return

Complex

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

artifacts-remaining

Simple

This is a numeric value indicating the number of artifacts remaining that can be drawn down. It is initially set to the number-of-labels in the request.

links

Complex

This structure represents a list of links to information relating to the open-return template that was created.

link

Complex

There are three link elements contained within the links structure, one with rel=”self”, one with rel=”details” and one with rel=”nextArtifact”.

<link
href="https://XX/rs/12435/454545/openreturn/676767
rel="self"
media-type="application/vnd.cpc.openreturn-v2+xml" />

<link
href="https://XX/rs/12435/454545/openreturn/6767/details
rel="details"
media-type="application/vnd.cpc.openreturn-v2+xml" />

<link
href="https://XX/rs/12435/454545/openreturn/6767676
rel="nextArtifact"
media-type="application/vnd.cpc.openreturn-v2+xml" />

Each link has three attributes as follows.

1. href. String. This is the endpoint that can be called using an http GET, POST or DELETE to execute the services:
   - Get Open Return Template
   - Get Open Return Template Details
   - Retrieve Next Open Return Artifact
   - Delete Open Return Template.

2. rel. String. This indicates the purpose of the link. In this case there are three possible values for rel=, as follows:

   rel="self"
   This indicates that the href link is a pointer to the open return template that was created; i.e., it can be used to call (using HTTP GET):
   - the Get Open Return Template service or
   - the Delete Open Return Template service for the template that was just created.

   rel="details"
   This indicates that the href link is a pointer that can be used to call (using HTTP GET) the Get Open Return Template Details service for the template that was created.

   rel="nextArtifact"
   This indicates that the href link is a pointer that allows the client to get the next artifact (i.e. label) that is available for retrieval; i.e., the href link can be used (using HTTP POST) to call the Get Next Open Return Artifact service for the template that was just created.

3. media-type. The media-type attribute indicates the format and structure of any additional input data that is required when invoking the web service indicated by href. This is usually a string indicating the appropriate version of Canada Post return web services.