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