Get started

This document provides guidance for using the Return Label API. The Carrier and Method Selection & Shipment Labels document provides more information about setting up your organization's account to use the Carrier and Method Selection service and print labels. The Fulfillment Contexts document includes guidance on configuring a returns type of fulfillment context to reference in your Return Label API calls.

The Return Label API is very closely related to the carrier and method selection and shipment label APIs, so you will find that many of the structures and components overlap with those.

Generate a return label

The Shipium Return Label API assumes you're using one of the authentication mechanisms detailed in our authentication documentation.

🔐
Authentication for API Calls
In the cURL example on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

Authenticating for Curl

Open Recipe

The following table provides required and optional fields for calling the Return Label API. You can find additional support in the Return Label API Reference.

Request field	Required/Optional	Field properties	Description
`currencyCode`	Required	String Example: `usd`	Currency in which all the rates for shipping carrier selection costs will be calculated
`generateLabel`	Optional	Boolean `true` or `false`	When `true`, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the `labelParameters` field of this object. When `false`, this step is skipped and the system will record what carrier service method for which a label would have been generated. The default value is `true`.
`labelParameters .testMode`	Optional	Boolean `true` or `false`	When `true`, calls to generate the labels will be made to the carrier sandbox servers. No actual labels are created, only a representation of the label. No money is charged to the underlying account.
`labelParameters .currencyCode`	Optional	String	Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters .labelFormats`	Required	String enumeration Supported formats are: `pdf` `png` `zpl` `printerless`	List of formats in which to generate the package label
`labelParameters .printerlessParameters`	Conditional	Object	Required when `printerless` is included in the `labelFormats` array*; specifies parameters for printerless label generation
`labelParameters .printerlessParameters .type`	Conditional	String Supported formats are: `qrcode`	Required when `printerless` is included in the `labelFormats` array*; the type of printerless label to generate
`labelParameters .printerlessParameters .imageFormat`	Conditional	String Supported formats are: `jpeg`	Required when `printerless` is included in the `labelFormats` array*; the desired image format for the printerless label
`labelParameters .eligibleForManifest`	Optional	Boolean `true` or `false`	When `true`, this label will be included in end-of-day and scheduled manifests. `False` indicates that the label should not be included in any manifests. The default value is `true`.
`labelParameters .includeLabelImages InResponse`	Optional	Boolean `true` or `false`	When `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters .contentDescription`	Optional	String	A short description (under 35 characters) of the package contents being returned that is passed on to the carrier; required for return shipments only
`labelParameters .customLabelEntries`	Optional	String	List of formats in which to generate the package label
`destinationAddress .addressType`	Optional, but some carriers require the destination address type	String enumeration Values are: `commercial` `residential`	The type of location for the destination address
`destinationAddress .company`	Optional	String	The company name for the destination address
`destinationAddress .name`	Optional	String	The name of the contact for the destination address
`destinationAddress .street1`	Optional	String	The first destination address line
`destinationAddress .street2`	Optional	String	The second destination address line
`destinationAddress .city`	Optional	String	The name of the city for the destination address
`destinationAddress .state`	Optional	String	The 2-letter postal abbreviation of the state for the destination address
`destinationAddress .postalCode`	Required	String	A country-code-appropriate postal code for the destination address
`destinationAddress .countryCode`	Required	String	The ISO 3166-1 country code for the destination address
`destinationAddress .phoneNumber`	Optional	String	The phone number of the contact for the destination address
`destinationAddress .phoneNumber CountryCode`	Optional	String	The phone number country code of the contact for the destination address
`originAddress .addressType`	Optional	String enumeration Values are: `commercial` `residential`	The type of location for the origin address
`originAddress.name`	Optional	String	The name of the contact for the origin address
`originAddress.company`	Optional	String	The company name for the origin address
`originAddress.street1`	Optional	String	The first origin address line
`originAddress.street2`	Optional	String	The second origin address line
`originAddress.city`	Optional	String	The name of the city for the origin address
`originAddress.state`	Optional	String	The 2-letter postal abbreviation of the state for the origin address
`originAddress .postalCode`	Required	String	A country-code-appropriate postal code for the origin address
`originAddress .countryCode`	Required	String	The ISO 3166-1 country code for the origin address
`originAddress .phoneNumber`	Optional	String	The phone number of the contact for the origin address
`originAddress .phoneNumber CountryCode`	Optional	String	The phone number country code of the contact for the origin address
`packagingType .packagingMaterial`	Conditional	String enumeration Values are: `box` `envelope` `flat_pack` `mailing_tube` `parcel_pallet`	The material type of the packaging. REQUIRED when`packagingTypeId` is not provided. OPTIONAL when `packagingTypeId` is provided; in this case, the value from the request will be used as a fallback if the `packagingMaterial` is not defined in the pre-configured packaging associated with the `packagingTypeId`.
`packagingType .packagingSizeName`	Optional	String Ex.: `13x12x10 box`	A custom name for the packaging
`packagingType .packagingTypeId`	Conditional	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The unique identifier for a pre-configured packaging type defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID. When this value is present, `linearDimensions` and `packagingMaterial` become optional as fallback fields. When this value is absent, `linearDimensions` and `packagingMaterial` are required.
`packagingType .linearDimensions .linearUnit`	Conditional	String enumeration Values are: `cm` (centimeter) `in` (inch)	The unit in which linear dimensions are provided REQUIRED when `packagingTypeId` is not provided.* OPTIONAL when `packagingTypeId` is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
`packagingType .linearDimensions .length`	Conditional	Number ($float) Ex.: `13`	The longest linear dimension (i.e., the longest side of a box or envelope) REQUIRED when `packagingTypeId` is not provided.* OPTIONAL when `packagingTypeId` is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
`packagingType .linearDimensions .width`	Conditional	Number ($float) Ex.: `12`	The second longest linear dimension (i.e., the second longest side of a box or envelope) REQUIRED when `packagingTypeId` is not provided.* OPTIONAL when `packagingTypeId` is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
`packagingType .linearDimensions .height`	Conditional	Number ($float) Ex.: `10`	The least long linear dimension (i.e., the shortest side of a box or envelope). Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. REQUIRED when `packagingTypeId` is not provided.* OPTIONAL when `packagingTypeId` is provided; in this case, the value from the request will be used as a fallback if dimensions are not defined in the pre-configured packaging.
`packagingType .packagingWeight .weightUnit`	Optional	String enumeration Values are: `g` (gram) `kg` (kilogram) `lb` (pound) `oz` (ounce)	The unit in which weight values are provided
`packagingType .packagingWeight .weight`	Optional	Number ($float) Ex.: `50`	The value of the weight
`totalWeight.weight`	Required	Number ($float) Ex.: `50`	The value of the weight of the empty packaging
`totalWeight .weightUnit`	Required	String enumeration Values are: `g` (gram) `kg` (kilogram) `lb` (pound) `oz` (ounce)	The unit in which weight values are provided
`orderItemQuantities .productId`	Optional, but required for international shipments and shipments containing hazardous materials	String Ex.: `RN03947--Z43121`	A product ID for the product being checked (ISBN, UPC, etc.)
`orderItemQuantities .quantity`	Optional, but required for international shipments and shipments containing hazardous materials	Integer ($int32) Ex.: `3`	The number of units of the product
`orderItemQuantities .productDetails`	Optional, but required for international shipments and shipments containing hazardous materials	String Ex.: `limited_quantity` (or `lq`) `ormd` (or `orm-d`) `perishable` `bound_printed_matter` (or `bpm`)	A list of properties that may affect the shipping of the product
`orderItemQuantities .shipiumOrderId`	Optional	String Ex.: `4dc43fff-c3af-4d7b-8a18-e01f2b4cb312`	A Shipium identification use to represent the group of delivery estimates purchased
`orderItemQuantities .partnerOrderId`	Optional	String Ex.: `myCustomPartnerOrderId123`	A unique identifier provided by your organization representing this order
`orderItemQuantities .hazmat`	Optional	Boolean `true` or `false`	If true, indicates that the item is hazardous materials; the default value is false. For details on hazmat information to include, you can refer to Hazardous Materials.
`customerReturnParams .partnerReturn RequestId`	Optional	String	An identification provided by your organization; limited to 30 alphanumeric characters; this unique ID is case sensitive.
`customerReturnParams .fulfillmentContext`	Optional	String	When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context for the returns.
`customerReturnParams .returnRequest DateTime`	Optional	String ($date-time)	ISO-8601 formatted date of the return request, if not set, the current date-time will be used.
`customerReturnParams .contentDescription`	Required	String	A short description (under 35 characters) of the package contents being returned that is passed on to the carrier
`referenceIdentifier`	Optional	String	An optional string identifier passed to the carrier; you may include up to 5 identifiers, appending numbers 2-5 to `referenceIdentifier`.

Example cURL request

The request looks very similar to a shipment label request. You pass information about the origin address and destination address, as shown in the cURL request below:

curl --request POST \
     --url <<api_url>>/api/v1/deliveryexperience/customerreturn/label
     --header 'accept: application/json' \
     --header $AUTHSTRING \
     --header 'content-type: application/json' \
     --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following example includes partnerReturnRequestId, customLabelEntries, and orderItemQuantities. All these are optional and can be omitted. You can find more details about custom label entries in Label Customization. The table describing request fields in the section above and the Return Label API Reference provide details about information to include in the API request.

{
    "currencyCode": "usd",
    "generateLabel": true,
    "labelParameters": {
        "testMode": true,
        "currencyCode": "usd",
        "labelFormats": [
            "zpl"
        ],
        "eligibleForManifest": true,
        "includeLabelImagesInResponse": true,
        "contentDescription": "General Merchandise",
        "customLabelEntries": {
            "order-number": "CUSTOM_ORDER_NUMBER"
        }
    },
    "destinationAddress": {
        "addressType": "commercial",
        "company": "Shipium Warehouse",
        "name": "Attn: RETURNS",
        "street1": "1234 Warehouse Way",
        "street2": "Suite 101",
        "city": "Reno",
        "state": "NV",
        "postalCode": "89521",
        "countryCode": "US"
    },
    "originAddress": {
        "addressType": "residential",
        "name": "Wile E. Coyote",
        "company": "ACME",
        "street1": "123 Warehouse St.",
        "street2": "Suite 42",
        "city": "Albuquerque",
        "state": "NM",
        "postalCode": "87121",
        "countryCode": "US"
    },
    "packagingType": {
        "packagingMaterial": "box",
        "packagingSizeName": "5x5x5 box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 5,
            "width": 5,
            "height": 5
        },
        "packagingWeight": {
            "weightUnit": "lb",
            "weight": 2
        }
    },
    "totalWeight": {
      "weight": 50,
      "weightUnit": "lb"
  },
    "orderItemQuantities": [
        {
            "productId": "MM-01-001",
            "quantity": 1
        },
        {
            "productId": "GR-08-001",
            "quantity": 1,
            "productDetails": [
                "ormd"
            ]
        }
    ],
    "customerReturnParams": {
        "partnerReturnRequestId": "customReturnRequestId",
        "fulfillmentContext": "8ad8e1a8-0656-4d18-afe8-d24fe3fc5f94",
        "returnRequestDateTime": "2021-01-11T00:00:00+00:00",
        "contentDescription": "General Merchandise"
    },
  "referenceIdentifier": "ReturnLane1",
  "referenceIdentifier2": "LVO-34"
}

Example response body

The return label response is almost identical to the response returned by the shipment label, though with some differences as carrier costing does not occur for return labels.

{
    "carrier": "ups",
    "carrierServiceName": "UPS Returns Service",
    "carrierShipmentId": "1Z204E380338943508",
    "carrierTrackingId": "1Z204E380338943508",
    "documents": [
        {
            "labelExpiration": "2020-11-19T21:11:42.628Z",
            "labelFormat": "zpl",
            "labelImage": {
                "imageEncoding": "base64",
                "imageContents": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACPTkDJAAACJElEQVRYCe1Vz0sbURCe2XWbiNZKRaxgEipIKYVSqFR7SuJRCipSDz1JD1Io4j/goe2l9xYPxYu9FLoRz/aUaCmUYKFee4hiKSg0ovVHY0x2nCe85e3GmM2Kl3bf5c3Mm/fN976ZZQGCFSgQKPC/K4AXEeDu6qemP9uHRi2M9eTITrUcXwS6l+Z7SmSZRHCvGrAzjnnQ6PnP+NhHZxxAcwe8+MdkvfFeXCBSGxLMda+Y19z4De6A8GPp1DQBdLVfvTm5s5eLFRFeslStMhcRZwHxrfTV3SJ6B0RdakzYTDhMh3CLzax6VkFAsDzeh1d8A3/v595zoUdsP2FC9tLDV56u9Q9t2QHFiKbNAzVXOQIq6xWKVxDI9Y7tRjOpKS7c+SBO2W9f6JdVQn492QpQoTgYWzKPVHBpM+8W8Vyvy9cQ8is3uUSH1yIyTwf94Xpy9Kv0xe6Q5AWRw1cTL8u2FYik53tZ5kVEWNhIPJ6IZFIz7D8DcpIURBoaQzfUGYh+Nu9TCVZqkTxXAUTrNhdsI6B+AYRAibOK1ypS77k9hH1x+JBd1vIhw1oVIHo4NEB/i0nSKttSKhRfRzJmSBajMlyXdr273YJ6Ll7aEHomwf3xnKskol62FPfU9DX1/JmftskNdp7Pw12gsvHDneOLgKFpkwz43Q1W3cc8IYyf9Vf0NQOy0J202XwAhj3IMu7e1xLDu/z/8NU2N1bgBwoECvx7CpwAEhquciKZh7kAAAAASUVORK5CYII="
            },
            "labelProperties": {
              "dpi": 203,
              "height": 6,
              "labelOrientation": "rotate_0",
              "linearUnits": "in",
              "width": 4
            },
            "labelUrl": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
        }
    ],
    "params": {
        "partnerReturnRequestId": "customReturnRequestId",
        "fulfillmentContext": "8ad8e1a8-0656-4d18-afe8-d24fe3fc5f94",
        "returnRequestDateTime": "2021-01-11T00:00:00+00:00",
        "contentDescription": "General Merchandise"
    },
   "packagingType": {
        "packagingMaterial": "box",
        "packagingSizeName": "5x5x5 box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 5,
            "width": 5,
            "height": 5
            },
        "packagingWeight": {
            "weightUnit": "lb",
            "weight": 2.0
            },
     "totalWeight": {
        "weight": 50,
        "weightUnit": "lb"
  },
    "serviceMethodName": "UPS Returns Service",
    "shipiumCustomerReturnLabelId": "4c6af31c-6f1d-4b20-a16f-a9110135e442",
    "status": "success",
    "statusDetails": "success",
    "referenceIdentifier": "ReturnLane1",
    "referenceIdentifier2": "LVO-34"
}

Example request body for a printerless label document

This example demonstrates requesting a QR code as the printerless label document for a Canada Post return.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "testMode": true,
    "currencyCode": "usd",
    "labelFormats": [
      "printerless"
],
    "printerlessParameters": {
      "type": "qrcode",
      "imageFormat": "jpeg"
    },
    "eligibleForManifest": true,
    "includeLabelImagesInResponse": true,
    "contentDescription": "General Merchandise"
  },
  "destinationAddress": {
    "addressType": "commercial",
    "company": "Shipium Warehouse",
    "name": "Attn: RETURNS",
    "street1": "1234 Warehouse Way",
    "city": "Reno",
    "state": "NV",
    "postalCode": "89521",
    "countryCode": "US"
  },
  "originAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "street1": "123 Warehouse St.",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "packagingType": {
    "packagingMaterial": "box",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 5,
      "width": 5,
      "height": 5
    }
  },
  "totalWeight": {
    "weight": 50,
    "weightUnit": "lb"
  },
  "customerReturnParams": {
    "fulfillmentContext": "8ad8e1a8-0656-4d18-afe8-d24fe3fc5f94"
  }
}

Example response with a printerless label document

When you request a printerless label format, the documents array will include an additional element with labelFormat set to "printerless" and a printerlessInfo object containing metadata about the QR code. The printerlessInfo object includes the QR code type and the URL encoded within it, allowing you to use the URL independently if needed.

{
  "carrier": "canadapost",
  "carrierServiceName": "Canada Post Returns",
  "documents": [
    {
      "labelFormat": "printerless",
      "labelImage": {
        "imageEncoding": "base64",
        "imageContents": "A534453...",
        "imageFormat": "jpeg"
      },
      "printerlessInfo": {
        "type": "qrcode",
        "valueRepresented": "https://ct.soa-gw.canadapost.ca/esto/app/bypass/label?key=d99978d9569c477cb4b68f071cac4806"
      }
    }
  ],
  "shipiumCustomerReturnLabelId": "4c6af31c-6f1d-4b20-a16f-a9110135e442",
  "status": "success"
}

Retrieve previously created labels

You can retrieve previously created labels by calling the same API endpoint you used to generate the label, using the GET request type and passing the returnLabelId you previously received in your response body.

Here's the cURL example call for retrieving a return label. You'll replace the returnLabelId value with the one you received during label generation.

curl --request GET \
     --url  <<api_url>/api/v1/deliveryexperience/customerreturn/label/{returnLabelId}
     --header 'accept: application/json' \
     --header $AUTHSTRING \
     --header 'content-type: application/json'

📘
More information on the API responses
As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: