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.

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

Conditional fields

Optional fields

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

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, though with some differences as carrier costing does not occur for return labels.

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

{
  "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

{
  "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:

• Terms and Definitions
• Troubleshooting Guide
• Contact Shipium Support

Updated 6 months ago

What’s Next

• Return Labels