Returns

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

Get Open Return Template Details – REST

Summary

Name: Get Open Return Template Details
Reason to Call: To retrieve an XML representation of all of the initial information related to an existing open return template. This includes the final return destination address details. This service would not typically be called during normal operations as it is not required to retrieve or print labels. It is provided for situations such as a recovery from a communications or other error.
Input: None – the endpoint href is a direct link to calling this service for a specific open return template.
Output:

The details that were input at the time that the open return template was created including:

  • address details of the final receiver
  • print preferences
  • settlement info
Version history: Release notes
Get Open Return Template Details – Summary of Service

Get Open Return Template Details – Summary of Service

Request Details

Request – Structure for Get Open Return Template Details

Endpoint

Invoke the link returned from a prior call to Create Open Return Template or Get Open Return Template where the value of the attribute “rel” is “details”.

HTTP Headers

HTTP Header Variable

Value

Accept

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

Content-Type

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

None

Request – Elements

Get Open Return Template Details does not require any input XML data.

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.

Get Open Return Template Details – Response Elements
Element Name Type Description

template-details

Simple

This is the top level XML structure for the response.

max-number-of-artifacts

Simple

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.

artifacts-remaining

Simple

Indicates the current remaining number of artifacts (return labels) allowed to be generated and retrieved using this template.

service-code

Simple

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

This structure contains data about the final destination. This data appears in the “To” address of the return label. Blank fields will have been removed during address formatting.

name

Simple

The name of the receiver

company

Simple

The company of the receiver

domestic-address

Complex

This structure contains the address data about the final receiver of the return shipment. 
Blank fields will have been removed for formatting of the labels.

address-line-1

Simple

Address line 1 of the receiver.

address-line-2

Simple

Address line 2 of the receiver.

city

Simple

City of receiver.

prov

Simple

Province of the receiver.

postal-code

Simple

Postal Code of the receiver

print-preferences

Complex

This structure contains print preferences for the labels, such as output format.

output-format

Simple

Valid values are:
- 8.5x11
- 4x6

encoding

Simple

{PDF}

show-packing-instructions

Simple

{true, false}
This element indicates whether packing instructions are to be included on the rendering of the label.

settlement-info

Complex

This structure contains the elements that indicate how the delivery will be settled (paid for).

contract-id

Simple

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

Response – XML Diagram

The following diagram shows the XML structure of the response from Get Open Return Template Details.

Get Open Return Template Details – Structure of the XML Response
Get Open Return Template Details – 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 MXL Request – Get Open Return Template Details

GET https://XX/PROVIDED LINK
Accept:application/vnd.cpc.openreturn+xml
Authorization:Basic s7HD7gwsennesc==

Note: Do not hard-code the HTTP endpoint link. The link is provided as an output from Create Open Return Template or Get Open Return Template.

Sample REST XML Response – Get Open Return Template Details

<open-return-details>
<artifacts-remaining>10</artifacts-remaining>
<open-return>
<max-number-of-artifacts>10</max-number-of-artifacts>
<service-code>DOM.EP</service-code>
<receiver>
<domestic-address>
<address-line-1>23 jardin private</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1K4T3</postal-code>
</domestic-address>
</receiver>
<print-preferences>
<output-format>8.5x11</output-format>
<encoding>PDF</encoding>
<show-packing-instructions>false</show-packing-instructions>
</print-preferences>
<settlement-info>
<contract-id>0012345678</contract-id>
</settlement-info>
</open-return>
</open-return-details>