Get started

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. Required and optional fields are defined in the table for the previous example.

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`	List of formats in which to generate the package label
`labelParameters .manifest`	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, but required for return shipments	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`	Optional	String enumeration Values are: - `box` - `envelope` - `flat_pack` - `mailing_tube` - `parcel_pallet`	The type of packaging used to create the package for the shipment
`packagingType .packagingSizeName`	Optional	String Ex.: `13x12x10 box`	A custom name for the packaging
`packagingType .packagingTypeId`	Optional, but required if `linearDimensions` is not provided	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The `packagingTypeId` that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, `linearDimensions` is required.
`packagingType .linearDimensions .linearUnit`	Optional, but required if the `packagingTypeId` is not included	String enumeration Values are: - `cm` (centimeter) - `in` (inch)	The unit in which linear dimensions are provided
`packagingType .linearDimensions .length`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `13`	The longest linear dimension (i.e., the longest side of a box or envelope)
`packagingType .linearDimensions .width`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `12`	The second longest linear dimension (i.e., the second longest side of a box or envelope)
`packagingType .linearDimensions .height`	Optional, but required if the `packagingTypeId` is not included	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.
`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`	Required	String Ex.: `RN03947--Z43121`	A product ID for the product being checked (ISBN, UPC, etc.)
`orderItemQuantities .quantity`	Required	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

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"
        ],
        "manifest": 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"
    }
}

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

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:

Return Label API

Get started

Generate a return label

📘
Authentication for API Calls

Example cURL request

Example request body

Example response body

Retrieve previously created labels

📘
More information on the API responses

Resources

Get started

Generate a return label

📘Authentication for API Calls

Example cURL request

Example request body

Example response body

Retrieve previously created labels

📘More information on the API responses

Resources

📘
Authentication for API Calls

📘
More information on the API responses