Return Label API

Generate a return label independent of shipment label generation with Shipium's Return Label API.

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.

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 fieldRequired/OptionalField propertiesDescription
currencyCodeRequiredString
Example: USD
Currency in which all the rates for shipping carrier selection costs will be calculated
generateLabelOptionalBoolean
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 would have generated a label for.
labelParameters.testModeOptionalBoolean
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.currencyCodeOptionalStringCurrency in which all the rates for shipping carrier selection costs will be calculated
labelParameters.labelFormatsRequiredString
Supported formats are:

- PDF
- PNG
- ZPL
List of formats to generate the package label in
labelParameters.manifestRequiredBoolean
True or False
When true, a manifest for the label is generated. While manifesting is optional, this field value must be provided.
labelParameters .includeLabelImagesInResponseOptionalBoolean
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 .contentDescriptionOptional, but required for return shipmentsStringA short description (under 35 characters) of the package contents being returned that is passed on to the carrier; required for return shipments only
labelParameters .customLabelEntriesOptionalStringList of formats in which to generate the package label
destinationAddress.addressTypeOptionalString enumeration
Values are:

- Commercial
- Residential
The type of location for the destination address
destinationAddress.companyOptionalStringThe company name for the destination address
destinationAddress.nameOptionalStringThe name of the contact for the destination address
destinationAddress.street1OptionalStringThe first destination address line
destinationAddress.street2OptionalStringThe second destination address line
destinationAddress.cityOptionalStringThe name of the city for the destination address
destinationAddress.stateOptionalStringThe 2-letter postal abbreviation of the state for the destination address
destinationAddress.postalCodeRequiredStringA country-code-appropriate postal code for the destination address
destinationAddress.countryCodeRequiredStringThe ISO 3166-1 country code for the destination address
originAddress.addressTypeOptionalString enumeration
Values are:

- Commercial
- Residential
The type of location for the origin address
originAddress.nameOptionalStringThe name of the contact for the origin address
originAddress.companyOptionalStringThe company name for the origin address
originAddress.street1OptionalStringThe first origin address line
originAddress.street2OptionalStringThe second origin address line
originAddress.cityOptionalStringThe name of the city for the origin address
originAddress.stateOptionalStringThe 2-letter postal abbreviation of the state for the origin address
originAddress.postalCodeRequiredStringA country-code-appropriate postal code for the origin address
originAddress.countryCodeRequiredStringThe ISO 3166-1 country code for the origin address
packagingType.packagingMaterialOptionalString enumeration
Values are:

- Box
- Envelope
- Flat_Pack
The type of packaging used to create the package for the shipment
packagingType.packagingSizeNameOptionalString
Example: 13x12x10 Box
A custom name for the packaging
packagingType.packagingTypeIdOptional, but required if linearDimensions is not providedString
Example: 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 .linearUnitOptional, but required if the packagingTypeId is not includedString enumeration
Values are:

- cm (centimeter)
- in (inch)
The unit in which linear dimensions are provided
packagingType.linearDimensions .lengthOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 13
The longest linear dimension (i.e., the longest side of a box or envelope)
packagingType.linearDimensions .widthOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 12
The second longest linear dimension (i.e., the second longest side of a box or envelope)
packagingType.linearDimensions .heightOptional, but required if the packagingTypeId is not includedNumber ($float)
Example: 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 .weightUnitOptionalString enumeration
Values are:

- g (gram)
- kg (kilogram)
- lb (pound)
- oz (ounce)
The unit in which weight values are provided
packagingType.packagingWeight .weightOptionalNumber ($float)
Example: 50
The value of the weight
orderItemQuantities.productIdRequiredString
Example: RN03947--Z43121
A product ID for the product being checked (ISBN, UPC, etc.)
orderItemQuantities.quantityRequiredInteger ($int32)
Example: 3
The number of units of the product
orderItemQuantities.productDetailsRequiredString
Ex.: Perishable
A list of properties that may affect the shipping of the product
customerReturnParams .partnerReturnRequestIdOptionalStringAn identification provided by your organization; limited to 30 alphanumeric characters; this unique ID is case sensitive.
customerReturnParams .fulfillmentContextOptionalStringWhen present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context for the returns.
customerReturnParams .returnRequestDateTimeOptionalString ($date-time)ISO-8601 formatted date of the return request, if not set, the current date-time will be used.
customerReturnParams .contentDescriptionRequiredStringA 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.0
            },
    "orderItemQuantities": [
        {
            "productId": "MM-01-001",
            "quantity": 1
        },
        {
            "productId": "GR-08-001",
            "quantity": 1,
            "productDetails": [
                "ormd"
            ]
        }
    ],
    "customerReturnParams": {
        "partnerReturnRequestId": "customReturnRequestId",
        "fulfillmentContext": "4c72f06e-ce7f-4580-ab44-4249adafd777",  
        "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": "4c72f06e-ce7f-4580-ab44-4249adafd777",
        "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
            },
    "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:


What’s Next