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

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.

Required fields

Field	Details
`currencyCode`	Type: String Example: `usd` Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters.labelFormats`	Type: String (enumeration) Values: `pdf`, `png`, `zpl`, `printerless` Description: List of formats in which to generate the package label
`destinationAddress.postalCode`	Type: String Description: A country-code-appropriate postal code for the destination address
`destinationAddress.countryCode`	Type: String Description: The ISO 3166-1 country code for the destination address
`originAddress.postalCode`	Type: String Description: A country-code-appropriate postal code for the origin address
`originAddress.countryCode`	Type: String Description: The ISO 3166-1 country code for the origin address
`totalWeight.weight`	Type: Number ($float) Example: `50` Description: The value of the weight of the empty packaging
`totalWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce) Description: The unit in which weight values are provided
`customerReturnParams.contentDescription`	Type: String 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 Condition: Required when `printerless` is included in the `labelFormats` array Description: Specifies parameters for printerless label generation
`labelParameters.printerlessParameters.type`	Type: String Values: `qrcode` Condition: Required when `printerless` is included in the `labelFormats` array Description: The type of printerless label to generate
`labelParameters.printerlessParameters .imageFormat`	Type: String Values: `jpeg` Condition: Required when `printerless` is included in the `labelFormats` array Description: The desired image format for the printerless label
`packagingType.packagingMaterial`	Type: String (enumeration) Values: `box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet` 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`. Description: The material type of the packaging
`packagingType.packagingTypeId`	Type: String Example: `ebd94f8b-d390-4c9c-987f-b88343f5bf45` Condition: Required when `linearDimensions` is not provided. When this value is present, `linearDimensions` and `packagingMaterial` become optional. Description: 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.
`packagingType.linearDimensions.linearUnit`	Type: String (enumeration) Values: `cm` (centimeter), `in` (inch) 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. Description: The unit in which linear dimensions are provided
`packagingType.linearDimensions.length`	Type: Number ($float) Example: `13` 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. Description: The longest linear dimension (i.e., the longest side of a box or envelope)
`packagingType.linearDimensions.width`	Type: Number ($float) Example: `12` 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. Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)
`packagingType.linearDimensions.height`	Type: Number ($float) Example: `10` 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. Description: 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.
`orderItemQuantities.productId`	Type: String Example: `RN03947--Z43121` Condition: Required for international shipments and shipments containing hazardous materials Description: A product ID for the product being checked (ISBN, UPC, etc.)
`orderItemQuantities.quantity`	Type: Integer ($int32) Example: `3` Condition: Required for international shipments and shipments containing hazardous materials Description: The number of units of the product
`orderItemQuantities.productDetails`	Type: String Example: `limited_quantity` (or `lq`), `ormd` (or `orm-d`), `perishable`, `bound_printed_matter` (or `bpm`) Condition: Required for international shipments and shipments containing hazardous materials Description: A list of properties that may affect the shipping of the product

Optional fields

Field	Details
`generateLabel`	Type: Boolean Values: `true` or `false` Description: 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`	Type: Boolean Values: `true` or `false` Description: 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`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters.eligibleForManifest`	Type: Boolean Values: `true` or `false` Description: 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.includeLabelImagesInResponse`	Type: Boolean Values: `true` or `false` Description: When `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters.contentDescription`	Type: String 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 Description: List of formats in which to generate the package label
`destinationAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the destination address. Some carriers require the destination address type.
`destinationAddress.company`	Type: String Description: The company name for the destination address
`destinationAddress.name`	Type: String Description: The name of the contact for the destination address
`destinationAddress.street1`	Type: String Description: The first destination address line
`destinationAddress.street2`	Type: String Description: The second destination address line
`destinationAddress.city`	Type: String Description: The name of the city for the destination address
`destinationAddress.state`	Type: String Description: The 2-letter postal abbreviation of the state for the destination address
`destinationAddress.phoneNumber`	Type: String Description: The phone number of the contact for the destination address
`destinationAddress.phoneNumberCountryCode`	Type: String Description: The phone number country code of the contact for the destination address
`originAddress.addressType`	Type: String (enumeration) Values: `commercial`, `residential` Description: The type of location for the origin address
`originAddress.name`	Type: String Description: The name of the contact for the origin address
`originAddress.company`	Type: String Description: The company name for the origin address
`originAddress.street1`	Type: String Description: The first origin address line
`originAddress.street2`	Type: String Description: The second origin address line
`originAddress.city`	Type: String Description: The name of the city for the origin address
`originAddress.state`	Type: String Description: The 2-letter postal abbreviation of the state for the origin address
`originAddress.phoneNumber`	Type: String Description: The phone number of the contact for the origin address
`originAddress.phoneNumberCountryCode`	Type: String Description: The phone number country code of the contact for the origin address
`packagingType.packagingSizeName`	Type: String Example: `13x12x10 box` Description: A custom name for the packaging
`packagingType.packagingWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce) Description: The unit in which weight values are provided
`packagingType.packagingWeight.weight`	Type: Number ($float) Example: `50` Description: The value of the weight
`orderItemQuantities.shipiumOrderId`	Type: String Example: `4dc43fff-c3af-4d7b-8a18-e01f2b4cb312` Description: A Shipium identification use to represent the group of delivery estimates purchased
`orderItemQuantities.partnerOrderId`	Type: String Example: `myCustomPartnerOrderId123` Description: A unique identifier provided by your organization representing this order
`orderItemQuantities.hazmat`	Type: Boolean Values: `true` or `false` 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.
`customerReturnParams.partnerReturnRequestId`	Type: String Description: An identification provided by your organization; limited to 30 alphanumeric characters; this unique ID is case sensitive.
`customerReturnParams.fulfillmentContext`	Type: String Description: When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context for the returns.
`customerReturnParams.returnRequestDateTime`	Type: String ($date-time) Description: ISO-8601 formatted date of the return request; if not set, the current date-time will be used.
`referenceIdentifier`	Type: String Description: 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: