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 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 | BooleanTrue 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.testMode | Optional | BooleanTrue 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 Supported formats are: - PNG - ZPL | List of formats to generate the package label in |
labelParameters.manifest | Required | BooleanTrue or False | When true , a manifest for the label is generated. While manifesting is optional, this field value must be provided. |
labelParameters .includeLabelImagesInResponse | Optional | BooleanTrue 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 | 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 |
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 |
packagingType.packagingMaterial | Optional | String enumeration Values are: - Box - Envelope - Flat_Pack | The type of packaging used to create the package for the shipment |
packagingType.packagingSizeName | Optional | String Example: 13x12x10 Box | A custom name for the packaging |
packagingType.packagingTypeId | Optional, but required if linearDimensions is not provided | String 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 .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) Example: 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) Example: 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) 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 .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) Example: 50 | The value of the weight |
totalWeight.weight | Required | Number ($float) Example: 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 Example: RN03947--Z43121 | A product ID for the product being checked (ISBN, UPC, etc.) |
orderItemQuantities.quantity | Required | Integer ($int32) Example: 3 | The number of units of the product |
orderItemQuantities.productDetails | Required | String Ex.: Perishable | A list of properties that may affect the shipping of the product |
customerReturnParams .partnerReturnRequestId | 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 .returnRequestDateTime | 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.0
}
},
"totalWeight": {
"weight": 50,
"weightUnit": "lb"
},
"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
},
"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:
Updated about 1 month ago