# Get started

This document provides guidance for using the Return Label API. The [Carrier and Method Selection & Shipment Labels](https://docs.shipium.com/docs/carrier-method-selection-label-single-call) 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](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/carrier-and-method-selection-api) and [shipment label](https://docs.shipium.com/docs/shipment-label-api) 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](https://docs.shipium.com/docs/authentication).

### 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.

## Request fields for API calls

The following tables provide required, conditional, and optional fields for calling the Return Label API. You can find additional support in the [Return Label API Reference](https://docs.shipium.com/reference/returnslabelcreatev1).

### Required fields

| Field | Details |
| --- | --- |
| `currencyCode` | **Type:** String<br>**Example:**`usd`<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `labelParameters.labelFormats` | **Type:** String (enumeration)<br>**Values:**`pdf`, `png`, `zpl`, `printerless`<br>**Description:** List of formats in which to generate the package [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) |
| `destinationAddress.postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the destination address |
| `destinationAddress.countryCode` | **Type:** String<br>**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the destination address |
| `originAddress.postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the origin address |
| `originAddress.countryCode` | **Type:** String<br>**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the origin address |
| `totalWeight.weight` | **Type:** Number (float)<br>**Example:**`50`<br>**Description:** The value of the weight of the empty packaging |
| `totalWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)<br>**Description:** The unit in which weight values are provided |
| `customerReturnParams.contentDescription` | **Type:** String<br>**Description:** A short description (under 35 characters) of the package contents being returned that is passed on to the carrier |

### Conditional fields

| Field | Details |
| --- | --- |
| `labelParameters.printerlessParameters` | **Type:** Object<br>**Condition:** Required when `printerless` is included in the `labelFormats` array<br>**Description:** Specifies parameters for printerless [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) generation |
| `labelParameters.printerlessParameters.type` | **Type:** String<br>**Values:**`qrcode`<br>**Condition:** Required when `printerless` is included in the `labelFormats` array<br>**Description:** The type of printerless [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) to generate |
| `labelParameters.printerlessParameters.imageFormat` | **Type:** String<br>**Values:**`jpeg`<br>**Condition:** Required when `printerless` is included in the `labelFormats` array<br>**Description:** The desired image format for the printerless [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) |
| `packagingType.packagingMaterial` | **Type:** String (enumeration)<br>**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`<br>**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if the `packagingMaterial` is not defined in the pre-configured packaging associated with the `packagingTypeId`.<br>**Description:** The material type of the packaging |
| `packagingType.packagingTypeId` | **Type:** String<br>**Example:**`ebd94f8b-d390-4c9c-987f-b88343f5bf45`<br>**Condition:** Required when `linearDimensions` is not provided. When this value is present, `linearDimensions` and `packagingMaterial` become optional.<br>**Description:** The unique identifier for a [pre-configured packaging type](https://docs.shipium.com/docs/shipium-carrier-selection-configuring-package-sizes) defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID. |
| `packagingType.linearDimensions.linearUnit` | **Type:** String (enumeration)<br>**Values:**`cm` (centimeter), `in` (inch)<br>**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).<br>**Description:** The unit in which linear dimensions are provided |
| `packagingType.linearDimensions.length` | **Type:** Number (float)<br>**Example:**`13`<br>**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).<br>**Description:** The longest linear dimension (i.e., the longest side of a box or envelope) |
| `packagingType.linearDimensions.width` | **Type:** Number (float)<br>**Example:**`12`<br>**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).<br>**Description:** The second longest linear dimension (i.e., the second longest side of a box or envelope) |
| `packagingType.linearDimensions.height` | **Type:** Number (float)<br>**Example:**`10`<br>**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).<br>**Description:** The least long linear dimension (i.e., the shortest side of a box or envelope)<br>**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. |
| `orderItemQuantities.productId` | **Type:** String<br>**Example:**`RN03947--Z43121`<br>**Condition:** Required for international shipments and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)<br>**Description:** A product ID for the product being checked (ISBN, UPC, etc.) |
| `orderItemQuantities.quantity` | **Type:** Integer (int32)<br>**Example:**`3`<br>**Condition:** Required for international shipments and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)<br>**Description:** The number of units of the product |
| `orderItemQuantities.productDetails` | **Type:** Array of strings<br>**Values:**`limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`)<br>**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)<br>**Description:** A list of product properties that affect carrier selection and handling; see [productDetails Reference](https://docs.shipium.com/docs/hazardous-materials-support#productdetails-reference) for details. |

### Optional fields

| Field | Details |
| --- | --- |
| `generateLabel` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, a request to the selected carrier will be sent to generate a [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) 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` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, calls to generate the labels will be made to the carrier sandbox servers. [No actual labels](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode) are created, only a representation of the label. No money is charged to the underlying account. |
| `labelParameters.currencyCode` | **Type:** String<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `labelParameters.eligibleForManifest` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, this label will be included in end-of-day and scheduled [manifests](https://docs.shipium.com/docs/shipment-manifesting). `False` indicates that the label should not be included in any manifests. The default value is `true`. |
| `labelParameters.includeLabelImagesInResponse` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, the response will include the raw image data of the [labels](https://docs.shipium.com/docs/carrier-shipment-label-flow) that were requested to be generated by the carrier. |
| `labelParameters.contentDescription` | **Type:** String<br>**Description:** 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` | **Type:** String<br>**Description:** List of formats in which to generate the [package label](https://docs.shipium.com/docs/carrier-shipment-label-flow) |
| `destinationAddress.addressType` | **Type:** String (enumeration)<br>**Values:**`commercial`, `residential`<br>**Description:** The type of location for the destination address. Some carriers require the destination address type. |
| `destinationAddress.company` | **Type:** String<br>**Description:** The company name for the destination address |
| `destinationAddress.name` | **Type:** String<br>**Description:** The name of the contact for the destination address |
| `destinationAddress.street1` | **Type:** String<br>**Description:** The first destination address line |
| `destinationAddress.street2` | **Type:** String<br>**Description:** The second destination address line |
| `destinationAddress.city` | **Type:** String<br>**Description:** The name of the city for the destination address |
| `destinationAddress.state` | **Type:** String<br>**Description:** The 2-letter postal abbreviation of the state for the destination address |
| `destinationAddress.phoneNumber` | **Type:** String<br>**Description:** The phone number of the contact for the destination address |
| `destinationAddress.phoneNumberCountryCode` | **Type:** String<br>**Description:** The phone number country code of the contact for the destination address |
| `originAddress.addressType` | **Type:** String (enumeration)<br>**Values:**`commercial`, `residential`<br>**Description:** The type of location for the origin address |
| `originAddress.name` | **Type:** String<br>**Description:** The name of the contact for the origin address |
| `originAddress.company` | **Type:** String<br>**Description:** The company name for the origin address |
| `originAddress.street1` | **Type:** String<br>**Description:** The first origin address line |
| `originAddress.street2` | **Type:** String<br>**Description:** The second origin address line |
| `originAddress.city` | **Type:** String<br>**Description:** The name of the city for the origin address |
| `originAddress.state` | **Type:** String<br>**Description:** The 2-letter postal abbreviation of the state for the origin address |
| `originAddress.phoneNumber` | **Type:** String<br>**Description:** The phone number of the contact for the origin address |
| `originAddress.phoneNumberCountryCode` | **Type:** String<br>**Description:** The phone number country code of the contact for the origin address |
| `packagingType.packagingSizeName` | **Type:** String<br>**Example:**`13x12x10 box`<br>**Description:** A custom name for the packaging |
| `packagingType.packagingWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)<br>**Description:** The unit in which weight values are provided |
| `packagingType.packagingWeight.weight` | **Type:** Number (float)<br>**Example:**`50`<br>**Description:** The value of the weight |
| `orderItemQuantities.shipiumOrderId` | **Type:** String<br>**Example:**`4dc43fff-c3af-4d7b-8a18-e01f2b4cb312`<br>**Description:** A Shipium identification use to represent the group of delivery estimates purchased |
| `orderItemQuantities.partnerOrderId` | **Type:** String<br>**Example:**`myCustomPartnerOrderId123`<br>**Description:** A unique identifier provided by your organization representing this order |
| `orderItemQuantities.hazmat` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** 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](https://docs.shipium.com/docs/hazardous-materials-support). |
| `customerReturnParams.partnerReturnRequestId` | **Type:** String<br>**Description:** An identification provided by your organization; limited to 30 alphanumeric characters; this unique ID is case sensitive. |
| `customerReturnParams.fulfillmentContext` | **Type:** String<br>**Description:** When present, this is used to limit carrier selection to carrier accounts that contain a matching [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts) for the returns. |
| `customerReturnParams.returnRequestDateTime` | **Type:** String (date-time)<br>**Description:** [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) formatted date of the return request; if not set, the current date-time will be used. |
| `referenceIdentifier` | **Type:** String<br>**Description:** An optional string [identifier](https://docs.shipium.com/docs/reference-fields-and-carrier-mappings) 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](https://docs.shipium.com/docs/shipment-label-api) request. You pass information about the origin address and destination address, as shown in the cURL request below:

```curl
curl --request POST \
     --url https://api.shipium.com/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](https://docs.shipium.com/docs/label-customization). The table describing request fields in the section above and the [Return Label API Reference](https://docs.shipium.com/reference/returnslabelcreatev1) provide details about information to include in the API request.

JSON

```json
{
    "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](https://docs.shipium.com/docs/shipment-label-api), though with some differences as carrier costing does not occur for return labels.

JSON

```json
{
    "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.

JSON

```json
{
  "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.

JSON

```json
{
  "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
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](https://docs.shipium.com/docs/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:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)

Updated 6 months ago

### What’s Next

- [Return Labels](https://docs.shipium.com/docs/return-labels)