Code Samples for Returns:  REST  |  SOAP

Returns

Create shipping labels for authorized and open returns.

number

Read Getting Started to find out how to sign up, get your API keys and more.

number

For essential information common to all our web services, read the Fundamentals of Canada Post Web Services:  REST  |  SOAP

Service Summary

The returns web service allows you to create shipping labels for authorized and open returns. Both generate “bill on scan” return labels that are not associated with a manifest and do not need to be associated with an outgoing label.

  • Authorized Returns – The address of both the sender and receiver are specified. The characteristics of the parcel are known and specified.
  • Open Returns – Only the address of the receiver (final receiver of the returned parcel) is specified. The characteristics of the parcel (weight, dimensions) are usually unknown and are captured when the parcel is inducted into Canada Post.

Note: A third type of return is designated and paid for at the time of a Create Shipment call (applies to contract shipping only). In this case, the Create Shipment service will render and provide the return label. For details, see Create Shipment.

Workflow and key services

Return service workflow and key services are shown below.

Authorized Returns

Authorized Returns

Authorized return functionality is provided through the following calls.

  1. Create Authorized Return
    REST   |    SOAP
    Used to create a return shipping label when the sender address and approximate package weight are known. This type of label is typically emailed through a self-serve or service agent process to the individual returning the item.
  2. Get Artifact
    REST   |    SOAP
    This call is used to retrieve the PDF or ZPL II document for the authorized return label.

Open Returns

Open Returns

Note: in the descriptions below, the “sender” is the original recipient who is sending the returned parcel back to its origin.

Open return functionality is provided through the following calls.

  1. Create Open Return Template
    REST   |    SOAP
    Used to request creation of generic labels for retrieval and printing. The sender address and parcel weight are unknown. Each label has a unique barcode, but the rest of the data is the same. The labels can be distributed as part of the original shipment, or sent to a specific individual.

    Notes:

    • The labels cannot all be generated at the start. Rather, a subset will be generated and available for draw down retrieval. As the labels get depleted to near zero, new ones will be generated to replenish the supply.
    • The maximum number of labels you can have pending is 100,000.
    • The maximum number of templates is 100.
    • Call Get Next Open Return Artifact to retrieve the next available artifact.
  2. Retrieve Next Open Return Artifact
    REST   |    SOAP
    Used to retrieve the PDF or ZPL II document for a return label artifact that was pre-established using Create Open Return Template.
  3. Get Open Return Template
    REST   |    SOAP
    Used to retrieve the information that allows access to the Retrieve Next Open Return Artifact service associated with the template.
    Note: This service returns an identical response to the Create Open Return Template call that created the template.
  4. Get Open Return Template Details
    REST   |    SOAP
    Used to retrieve the information you originally provided when you called Create Open Return Template to create the template (e.g. the number of labels you specified for this template; the receiver). This call also provides the number of remaining labels for this template.
  5. Delete Open Return Template
    REST   |    SOAP
    Used to delete an existing active open return template.
  6. Get Open Return Templates
    REST   |    SOAP
    Used to retrieve the list of active open return templates (based on the mailed-on-behalf-of customer number). Active open return templates are those that still have open return artifacts available for retrieval. Once all of the artifacts from a template have been retrieved, the open return template is consider depleted, and is deleted.