Returns

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

Create Open Return Template – REST

Summary

Name: Create Open Return Template
Reason to Call: Used to create a number of generic return shipping labels (up to 100,000) where the sender address and weight are unknown.
Input: Shipping input information
Output: Links to the created template as well as a link to the service to retrieve the return labels.
Error Example: Errors in address or parcel characteristics.
Typical Next Call: Retrieve Next Open Return Artifact.
Version history: Release notes
Create Open Return Template

Create Open Return Template

Request Details

Request – Structure for Create Open Return Template

Endpoint

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

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

Body

<?xml version="1.0" encoding="utf-8"?>
<open-return xmlns=”http://www.canadapost.ca/ws/openreturn-v2”>
xxx
</open-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 Open Return Template – Request Elements
Element Name Type Required / Optional Description

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.

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

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:

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

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.

Request – XML Diagram

The following is the hierarchical structure of the XML for the request to Create Open Return Template.

Create Open Return Template – Structure of the XML Request

Create Open Return Template – Structure of the XML Request

Response Details

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

Create Open Return Template – Response Elements
Element Name Type Description

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

Examples

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

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

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

Response – XML Diagram

The following diagram shows the XML structure of the response from the Create Open Return Template service.

Create Open Return Template – Structure of the XML Response

Create Open Return Template – 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.

Possible error messages for this service include the following:

HTTP Status Code Application Error Message
500 N/A Detailed schema validation error is provided.
412 9999

Examples

Sample REST XML Request – Create Open Return Template

<open-return>
<max-number-of-artifacts>10</max-number-of-artifacts>
<service-code>DOM.EP</service-code>
<receiver>
<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>
<print-preferences>
<output-format>8.5x11</output-format>
</print-preferences>
<settlement-info>
<contract-id>12345678</contract-id>
</settlement-info>
</open-return>

Sample REST XML Response – Create Open Return Template

<open-return-info>
<artifacts-remaining>10</artifacts-remaining>
<links>
<linkrel="self"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649"media-type="application/vnd.cpc.openreturn-v2+xml"></link>
<linkrel="details"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649/details"media-type="application/vnd.cpc.openreturn-v2+xml"></link>
<linkrel="nextArtifact"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649/artifact"media-type="application/pdf"></link>
</links>
</open-return-info>