Returns

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

Create Open Return Template – SOAP

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: A template ID to retrieve the return label and the number of labels remaining on this template available for draw down.
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

Call Details

WSDL: openreturn.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca/rs/soap/openreturn/v2
Endpoint (Production): https://soa-gw.canadapost.ca/rs/soap/openreturn/v2
Namespace: http://www.canadapost.ca/ws/soap/openreturn/v2
Operation: CreateOpenReturnTemplate

SOAP Body

This section describes the XML input elements to this service. For the hierarchical structure, see the XML diagram.

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

create-open-return-template-request

complex

required

The top level element for the request.

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.

open-return

complex

required

The structure containing details about the return label.

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

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

Create Open Return Template – Structure of the XML Request
Create Open Return Template – Structure of the XML Request

Response Details

Response – Elements

The following table describes the XML elements in the response to Create Open Return Template. For the hierarchy of the response, see the XML diagram.

Create Open Return Template – Response Elements
Element Name Type Description

create-open-return-template-response

complex

This is the top level XML element for the response.

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

open-return

complex

This structure contains the results of a successful completion of the service.

artifacts-remaining

simple

The number of artifacts remaining that can be drawn down. It is initially set to the number of labels in the request.

template-id

simple

An identification number representing the template that was just created.

Response – XML Diagram

Create Open Return Template – Structure of the XML Response

Create Open Return Template – Structure of the XML Response

Response – Possible Error Responses

The response to error conditions for this web service follows the standard SOAP error response approach used for all Canada Post web services. For more information, see SOAP Fundamentals of Canada Post Web Services.

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 SOAP XML Request – Create Open Return Template

<create-open-return-template-request>
<mailed-by>1111111</mailed-by>
<locale>EN</locale>
<open-return>
<max-number-of-artifacts>15</max-number-of-artifacts>
<service-code>DOM.EP</service-code>
<receiver>
<domestic-address>
<address-line-1>2701 Return 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>
</create-open-return-template-request>

Sample SOAP XML Response – Create Open Return Template

<create-open-return-template-response>
<open-return-info>
<artifacts-remaining>10</artifacts-remaining>
<template-id>349641323786705649</template-id>
</open-return-info>
</create-open-return-template-response>