For AI agents: visit https://docs.shipium.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.
# About return labels [Skip link to About return labels](https://docs.shipium.com/docs/return-labels\#about-return-labels)
Many retail companies enable their customers to send back products due to issues with a product or as part of their business model. Most shipping carriers have a different return method that enables you, the shipper, to:
- not get charged for shipping the package until the label is scanned (some carriers do charge a fee per requested return label, however);
- print a label with a tentative weight or no weight at all; and
- specify your fulfillment center as the destination and a customer location as the origin.
> 👍
>
> ### Recommended approach [Skip link to Recommended approach](https://docs.shipium.com/docs/return-labels\#recommended-approach)
>
> For new implementations, Shipium recommends generating return labels inline with your outbound shipment using the [Carrier and Method Selection & Shipment Label API](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api). This approach enables you to obtain both an outbound shipping label and a return label in a single API call.
The Shipium system supports return label generation and offers three ways for you to retrieve a return shipment label:
- **Generate a return label at the same time as shipment label generation (recommended).** This method involves including additional data fields when calling the [Carrier and Method Selection & Shipment Label API](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api). Instructions are included in this document.
- **Generate a return label independent of shipment label generation.** This method involves calling the Return Label API. This approach is useful when you need to create return labels separately from the original shipment workflow. Instructions are included in the [Return Label API](https://docs.shipium.com/docs/return-label-api) document.
- **Print ad-hoc return labels from the Shipium Console.** This method satisfies the need to create ad-hoc return labels for customers. Guidance is included in the [Print Labels](https://docs.shipium.com/docs/print-labels) document.
You also can [retrieve previously created return labels](https://docs.shipium.com/docs/return-labels#retrieve-previously-created-labels) via an API call.
> 👉
>
> ### Test mode [Skip link to Test mode](https://docs.shipium.com/docs/return-labels\#test-mode)
>
> Want to run some examples and not charge any real money against your account?
>
> You can add `testMode`: "true" to the data passed to any label call to retrieve labels without charging money in a carrier-specific manner. Most carriers will mark their labels in a way to make clear that they are void, such as inserting "VOID" throughout the label or using a predefined ID.
>
> Examples below all contain the `testMode` flag to err on the side of caution – remove it to make production calls.
# Generate a return label at the same time as shipment label generation [Skip link to Generate a return label at the same time as shipment label generation](https://docs.shipium.com/docs/return-labels\#generate-a-return-label-at-the-same-time-as-shipment-label-generation)
With this option, you can make a single call to Shipium's [Carrier and Method Selection & Shipment Label API](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) and receive both an outbound shipping label and a return label rate shopped across three national carriers: FedEx, United Parcel Service (UPS), and United States Postal Service (USPS).
> 📘
>
> ### Authentication for API calls [Skip link to Authentication for API calls](https://docs.shipium.com/docs/return-labels\#authentication-for-api-calls)
>
> In the cURL examples 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](https://docs.shipium.com/docs/api-key-based-authentication) and [OAuth](https://docs.shipium.com/docs/oauth-20-based-authentication) users.
🔐
Authenticating for Curl
Open Recipe
The [Carrier and Method Selection & Shipment Label API](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) document provides an overview of special cases that can be handled when calling the API, such as hazardous material. Those same cases are supported for return labels as well.
The following tables provide required, conditional, and optional field descriptions for calling to retrieve a return label and shipment label simultaneously. You can find additional support in [Carrier and Method Selection & Shipment Label API Reference](https://docs.shipium.com/reference/runmegashipmentprocessv1).
## Required fields [Skip link to Required fields](https://docs.shipium.com/docs/return-labels\#required-fields)
| Request field | Details |
| --- | --- |
| `inlineReturnsLabel.returnToAddress.countryCode` | **Type:** String
**Example:**`US`
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.postalCode` | **Type:** String
**Example:**`87121`
**Description:** A country-code-appropriate postal code for the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial` or `residential`
**Description:** The type of location for this return-to address (for the return label) |
| `currencyCode` | **Type:** String
**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `shipmentParameters.destinationAddress.countryCode` | **Type:** String
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the destination address |
| `shipmentParameters.destinationAddress.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the destination address |
| `shipmentParameters.destinationAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial` or `residential`
**Description:** The type of location for the destination address |
| `shipmentParameters.shipFromAddress.countryCode` | **Type:** String
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the origin address |
| `shipmentParameters.shipFromAddress.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the origin address |
## Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/return-labels\#conditional-fields)
| Request field | Details |
| --- | --- |
| `inlineReturnsLabel.fulfillmentContext` | **Type:** String
**Condition:** Required for multiple returns in the shipment
**Description:** When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context for the returns. It must be a **Returns** type fulfillment context, and if it is included, the `returnToAddress` information is optional. You can find guidance on setting up a returns fulfillment context in [Fulfillment Contexts](https://docs.shipium.com/docs/fulfillment-contexts). |
| `shipmentParameters.orderItemQuantities .productDetails` | **Type:** Array of strings
**Values:**`limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`)
**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)
**Description:** A list of product properties that affect carrier selection and handling; see [productDetails Reference](https://docs.shipium.com/docs/hazardous-materials-support#productdetails-reference) for details. |
| `shipmentParameters.orderItemQuantities .productId` | **Type:** String
**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)
**Description:** A product ID for the product being checked (ISBN, UPC, etc.) |
| `shipmentParameters.orderItemQuantities .quantity` | **Type:** Integer (int32)
**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)
**Description:** The number of units of the product |
| `shipmentParameters.fulfillmentContext` | **Type:** String
**Condition:** Required if your organization has more than one returns type [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts)
**Description:** This is used to limit carrier selection to carrier accounts that contain a matching fulfillment context. |
| `shipmentParameters.packagingType .linearDimensions.height` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided
**Description:** The least long linear dimension (i.e., the shortest side of a box or envelope)
**Note:** For 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. |
| `shipmentParameters.packagingType .linearDimensions.length` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided
**Description:** The longest linear dimension (i.e., the longest side of a box or envelope) |
| `shipmentParameters.packagingType .linearDimensions.linearUnit` | **Type:** String (enumeration)
**Values:**`cm` (centimeter) or `in` (inch)
**Condition:** Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided
**Description:** The unit in which linear dimensions are provided |
| `shipmentParameters.packagingType .linearDimensions.width` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided
**Description:** The second longest linear dimension (i.e., the second longest side of a box or envelope) |
| `shipmentParameters.packagingType .packagingMaterial` | **Type:** String (enumeration)
**Values:**`box`, `envelope`, `flat_pack`
**Condition:** Required when `packagingTypeId` is not provided; optional when `packagingTypeId` is provided
**Description:** The material type of the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) |
| `shipmentParameters.packagingType .packagingTypeId` | **Type:** String
**Example:**`ebd94f8b-d390-4c9c-987f-b88343f5bf45`
**Condition:** When provided, `linearDimensions` and `packagingMaterial` become optional fields; when absent, `linearDimensions` and `packagingMaterial` are required.
**Description:** The unique identifier for a [pre-configured packaging type](https://docs.shipium.com/docs/configure-packaging-configuration) defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID. |
| `shipmentParameters.returnToAddress .countryCode` | **Type:** String
**Condition:** Required if including a `returnToAddress` in `shipmentParameters`
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress .postalCode` | **Type:** String
**Condition:** Required if including a `returnToAddress` in `shipmentParameters`
**Description:** A country code appropriate postal code for the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
## Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/return-labels\#optional-fields)
| Request field | Details |
| --- | --- |
| `inlineReturnsLabel.partnerShipmentId` | **Type:** String
**Example:**`myCustomPartnerShipmentId123`
**Description:** An optional unique identifier that your organization may use for this shipment |
| `inlineReturnsLabel.returnToAddress.city` | **Type:** String
**Description:** The name of the city for the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.company` | **Type:** String
**Description:** The company name for the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.emailAddress` | **Type:** String
**Description:** The email address for the contact associated with the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.name` | **Type:** String
**Description:** The name associated with the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.phoneNumber` | **Type:** String
**Description:** The phone number for the contact associated with the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.state` | **Type:** String
**Description:** The 2-letter abbreviation of the state for the address of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.street1` | **Type:** String
**Description:** The first address line of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToAddress.street2` | **Type:** String
**Description:** The second address line of the location where the package is being returned (for the return label) |
| `inlineReturnsLabel.returnToContactInfo.contactName` | **Type:** String
**Description:** The name of the contact for the return-to address |
| `inlineReturnsLabel.returnToContactInfo.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the return-to address |
| `inlineReturnsLabel.returnToContactInfo .phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact for the return-to address |
| `inlineReturnsLabel.returnToContactInfo.email` | **Type:** String
**Description:** The email address of the contact for the return-to address |
| `inlineReturnsLabel.inlineReturnReferenceIdentifier` | **Type:** String
**Description:** An optional string identifier passed to the carrier; you may include up to 5 identifiers, appending numbers 2-5 to `inlineReturnReferenceIdentifier`. |
| `inlineReturnsLabel.saturdayDelivery` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that the shipment is marked for [Saturday delivery](https://docs.shipium.com/docs/weekend-and-holiday-delivery). It does not guarantee delivery on Saturday. |
| `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 would have generated a label for. The default value is `true`. |
| `labelParameters.currencyCode` | **Type:** String
**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `labelParameters.customLabelEntries` | **Type:** String
**Description:** List of formats in which to generate the package label |
| `labelParameters.includeLabelImagesInResponse` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier. |
| `labelParameters.labelFormats` | **Type:** String (enumeration)
**Values:**`pdf`, `png`, `zpl`
**Description:** List of formats in which to generate the package label |
| `labelParameters.eligibleForManifest` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, or null, this label will be included in end-of-day and scheduled [manifests](https://docs.shipium.com/docs/shipment-manifesting); `false` indicates that the label should not be included in any manifests. |
| `labelParameters.contentDescription` | **Type:** String
**Description:** A brief description of the contents being returned that is passed to the carrier; must be 1-35 characters |
| `shipmentParameters.destinationAddress.city` | **Type:** String
**Description:** The name of the city for the destination address |
| `shipmentParameters.destinationAddress.company` | **Type:** String
**Description:** The company name for the destination address |
| `shipmentParameters.destinationAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact for the destination address |
| `shipmentParameters.destinationAddress.name` | **Type:** String
**Description:** The name of the contact for the destination address |
| `shipmentParameters.destinationAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the destination address |
| `shipmentParameters.destinationAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the destination address |
| `shipmentParameters.destinationAddress.street1` | **Type:** String
**Description:** The first destination address line |
| `shipmentParameters.destinationAddress.street2` | **Type:** String
**Description:** The second destination address line |
| `shipmentParameters.orderItemQuantities .deliveryEstimateId` | **Type:** String
**Description:** The Delivery Estimate ID associated with the product |
| `shipmentParameters.orderItemQuantities.hazmat` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that the item is [hazardous material](https://docs.shipium.com/docs/hazardous-materials-support) (hazmat). The default value is `false`. |
| `shipmentParameters.orderItemQuantities .shipiumOrderId` | **Type:** String
**Description:** Identification used to represent the group of delivery estimates purchased |
| `shipmentParameters.shipFromAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial` or `residential`
**Description:** The type of location for the origin address |
| `shipmentParameters.shipFromAddress.city` | **Type:** String
**Description:** The name of the city for the origin address |
| `shipmentParameters.shipFromAddress.company` | **Type:** String
**Description:** The company name for the origin address |
| `shipmentParameters.shipFromAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact for the origin address |
| `shipmentParameters.shipFromAddress.name` | **Type:** String
**Description:** The name of the contact for the origin address |
| `shipmentParameters.shipFromAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the origin address |
| `shipmentParameters.shipFromAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the origin address |
| `shipmentParameters.shipFromAddress.street1` | **Type:** String
**Description:** The first origin address line |
| `shipmentParameters.useShipFromAddressInRequest` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, this optional field overrides the shipper's contact name and address configured for the shipping origin in the Shipium Console, opting to use the `shipFromAddress` information passed in the API call. If shipping with carrier [LaserShip](https://docs.shipium.com/docs/lasership), use caution with this flag as the carrier's strict address matching could result in an error. |
| `shipmentParameters.returnToAddress.name` | **Type:** String
**Description:** The name associated with the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact associated with the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress .phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact associated with the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact associated with the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.company` | **Type:** String
**Description:** The company of the contact associated with the address of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.street1` | **Type:** String
**Description:** The first address line of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.street2` | **Type:** String
**Description:** The second address line of the location where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.city` | **Type:** String
**Description:** The city of the location where the package is being returned; this return-to address will override a r [eturn-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.state` | **Type:** String
**Description:** The 2-letter abbreviation of the location's state where the package is being returned; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.returnToAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the return-to address; this return-to address will override a [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) configured for an origin or carrier account. |
| `shipmentParameters.deliveredDateTime` | **Type:** String (date-time)
**Description:** The timestamp for when the package was delivered to the customer; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. |
| `shipmentParameters.desiredDeliveryDate` | **Type:** String
**Description:** The string representation of either an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date or a LocalDate: `yyyy-mm-dd`. The date or datetime the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. |
| `shipmentParameters.orderedDateTime` | **Type:** String (date-time)
**Description:** The timestamp for when the customer placed the order for this product; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. |
| `shipmentParameters.testMode` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, a test mode shipment will be created. Carrier selection will consider carriers and service methods in test mode, and label generation will generate a [test label](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode). |
| `shipmentParameters.packagingType .packagingSizeName` | **Type:** String
**Example:**`13x12x10 box`
**Description:** A custom name for the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) |
| `shipmentParameters.packagingType .packagingWeight.weight` | **Type:** Number (float)
**Description:** The value of the weight |
| `shipmentParameters.packagingType .packagingWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `shipmentParameters.referenceIdentifier` | **Type:** String
**Description:** String passed to carriers as a [reference](https://docs.shipium.com/docs/reference-fields-and-carrier-mappings) |
| `shipmentParameters.saturdayDelivery` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that the shipment is marked for [Saturday delivery](https://docs.shipium.com/docs/weekend-and-holiday-delivery). It does not guarantee delivery on Saturday. |
| `shipmentParameters.shipOption` | **Type:** String
**Example:**`standard`
**Description:** A high-level [shipping option](https://docs.shipium.com/docs/shipment-ship-option-overview) shown to or selected by a customer |
| `shipmentParameters.shipmentTags` | **Type:** String
**Description:** A collection of free-form tags that may be added to the shipment |
| `shipmentParameters.shippedDateTime` | **Type:** String (date-time)
**Description:** The timestamp for when a partner will ship the product from their warehouse; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. If not provided, this value defaults to `orderedDateTime`. |
| `shipmentParameters.totalWeight.weight` | **Type:** Number (float)
**Description:** The value of the weight |
| `shipmentParameters.totalWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
## Example cURL request [Skip link to Example cURL request](https://docs.shipium.com/docs/return-labels\#example-curl-request)
cURL
```curl
curl --request POST
--url https://api.shipium.com/api/v1/shipment/carrierselection/label
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
```
## Example request body [Skip link to Example request body](https://docs.shipium.com/docs/return-labels\#example-request-body)
When requesting a return label at the same time as the original shipment label generation, you'll add the `inlineReturnsLabel` object to your call, as shown in the following example. The `returnToAddress` and `returnToContact` fields for the `inlineReturnsLabel` are optional when providing fulfillment context values; you can provide values for these fields if you wish to override an address or contact information (for the return label) associated with an existing [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts) in the Shipium platform. A fulfillment context value can be provided in the call to associate the return to a **Returns** type fulfillment context that your organization has set up for returns. You can find more information about setting up a fulfillment context in [Fulfillment Contexts](https://docs.shipium.com/docs/fulfillment-contexts).
In addition to the override for the return-to address and contact information for the return label, you can include an override for any configured values for the outbound label's return-to address. To provide this override, you would add the `returnToAddress` fields to `shipmentParameters`, as shown in the following example.
JSON
```json
{
"inlineReturnsLabel": {
"partnerShipmentId": "myCustomPartnerShipmentId123",
"returnToAddress": {
"countryCode": "US",
"postalCode": "17901",
"addressType": "commercial",
"city": "Pottsville",
"company": "Sell It",
"emailAddress": "rodrunner@sellit.com",
"name": "Ro Drunner",
"phoneNumber": "5555555555",
"state": "PA",
"street1": "401 Centre St."
},
"returnToContactInfo": {
"contactName": "Ro Drunner",
"phoneNumber": "5555555555",
"phoneNumberCountryCode": "1",
"email": "rodrunner@sellit.com"
},
"fulfillmentContext": "b4a3e646-4a10-4c7b-b974-1f115c9890c5",
"inlineReturnReferenceIdentifier": "ReturnLane1",
"inlineReturnReferenceIdentifier2": "LVO-34",
"saturdayDelivery": true
},
"currencyCode": "usd",
"generateLabel": true,
"labelParameters": {
"currencyCode": "usd",
"customLabelEntries": {},
"includeLabelImagesInResponse": true,
"labelFormats": [\
"zpl"\
],
"eligibleForManifest": true,
"contentDescription": "general merchandise"
},
"shipmentParameters": {
"destinationAddress": {
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial",
"city": "Albuquerque",
"company": "Buy It",
"emailAddress": "wilecoyote@buyit.com",
"name": "Wile E. Coyote",
"phoneNumber": "888-555-1234",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42"
},
"orderItemQuantities": [\
{\
"productDetails": [\
],\
"productId": "RN03947--Z43121",\
"quantity": 3,\
"deliveryEstimateId": "feea39ed-20c6-4b3b-98dd-34bf1d89a933",\
"hazmat": false,\
"shipiumOrderId": "b0f7037a-2f37-4df8-b350-8ee1fb6eadec"\
}\
],
"shipFromAddress": {
"countryCode": "US",
"postalCode": "17901",
"addressType": "commercial",
"city": "Pottsville",
"company": "Sell It",
"emailAddress": "rodrunner@sellit.com",
"name": "Ro Drunner",
"phoneNumber": "6612475319",
"state": "PA",
"street1": "401 N. Centre St."
},
"returnToAddress": {
"name": "Rod Runner",
"phoneNumber": "865-433-9999",
"phoneNumberCountryCode": "+2",
"emailAddress": "rod@acme.com",
"company": "ACME",
"street1": "456 Main St.",
"street2": "Suite 8",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"deliveredDateTime": "2019-10-31T10:50:11.123456Z",
"desiredDeliveryDate": "2019-10-31T20:00:00Z",
"fulfillmentContext": "47e5608b-b606-426c-b3e2-b13acb1af22d",
"orderedDateTime": "2019-10-29T09:12:33.123456Z",
"testMode": true,
"packagingType": {
"linearDimensions": {
"height": 5,
"length": 5,
"linearUnit": "in",
"width": 5
},
"packagingMaterial": "box",
"packagingSizeName": "5x5x5 box",
"packagingWeight": {
"weight": 2,
"weightUnit": "lb"
}
},
"referenceIdentifier": "PSFC-2478",
"saturdayDelivery": false,
"shipOption": "standard",
"shipmentTags": [\
"PSFC",\
"Returns"\
],
"shippedDateTime": "2019-10-29T09:12:33.123456Z",
"totalWeight": {
"weight": 10,
"weightUnit": "lb"
}
}
}
```
## Example response body [Skip link to Example response body](https://docs.shipium.com/docs/return-labels\#example-response-body)
JSON
```json
{
"shipiumShipmentId": "ba1919a1-1c9a-4f53-93a7-8af49213be7c",
"orderedDateTime": "2019-10-29T09:12:33.123456Z",
"shippedDateTime": "2019-10-29T09:12:33.123456Z",
"returnsLabel": {
"shipiumShipmentId": "490b4ee3-147e-455b-aca7-a70456a58104",
"carrierSelectionId": "c7ca006a-7c45-42df-a863-ffdca2225a93",
"shipiumLabelId": "fdb3fa70-ddc7-4c27-abf0-29b8bb1e55eb",
"carrier": "fedex",
"carrierServiceName": "FedEx Corporation Account - 2",
"serviceMethodName": "FedEx Home Delivery",
"carrierServiceMethodId": "fedex-home-delivery-service-method",
"documents": [\
{\
"labelExpiration": "2024-05-02T17:23:29.903Z",\
"labelFormat": "zpl",\
"labelProperties": {\
"height": 6.0,\
"width": 4.0,\
"linearUnits": "in",\
"dpi": 203,\
"labelOrientation": "rotate_0"\
},\
"labelImage": {\
"imageEncoding": "base64",\
"imageContents": "..."\
},\
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/490b4ee3-147e-455b-aca7-a70456a58104/carrierSelection/c7ca006a-7c45-42df-a863-ffdca2225a93/label/fdb3fa70-ddc7-4c27-abf0-29b8bb1e55eb/zpl",\
"carrierTrackingId": "123456",\
"carrierTrackingLink": "www.tracking-link.com",\
"carrierShipmentId": "123456"\
}\
],
"internationalDocuments": []
},
"ignoreUpgradeSpendLimits": false,
"deliveredDateTime": "2019-10-31T10:50:11.123456Z",
"fulfillmentType": "customer",
"packages": [\
{\
"orderItemQuantities": [\
{\
"productId": "RN03947--Z43121",\
"quantity": 3,\
"productDetails": [],\
"shipiumOrderId": "b0f7037a-2f37-4df8-b350-8ee1fb6eadec",\
"hazmat": false\
}\
],\
"packagingType": {\
"packagingMaterial": "box",\
"packagingSizeName": "5x5x5 box",\
"linearDimensions": {\
"linearUnit": "in",\
"length": 5,\
"width": 5,\
"height": 5\
},\
"packagingWeight": {\
"weightUnit": "lb",\
"weight": 2.0\
}\
},\
"totalWeight": {\
"weightUnit": "lb",\
"weight": 10.0\
},\
"deliveredDateTime": "2019-10-31T10:50:11.123456Z",\
"orderItemQuantities": [\
{\
"productId": "RN03947--Z43121",\
"quantity": 3,\
"productDetails": [],\
"shipiumOrderId": "b0f7037a-2f37-4df8-b350-8ee1fb6eadec",\
"hazmat": false\
}\
],\
"destinationAddress": {\
"name": "Wile E. Coyote",\
"phoneNumber": "888-555-1234",\
"emailAddress": "wilecoyote@buyit.com",\
"company": "Buy It",\
"street1": "123 Main St.",\
"street2": "Suite 42",\
"city": "Albuquerque",\
"state": "NM",\
"countryCode": "US",\
"postalCode": "87121",\
"addressType": "commercial"\
},\
"shipOption": "standard",\
"shipFromAddress": {\
"name": "Ro Drunner",\
"phoneNumber": "5555555555",\
"emailAddress": "rodrunner@sellit.com",\
"company": "Sell It",\
"street1": "401 Centre St.",\
"city": "Pottsville",\
"state": "PA",\
"countryCode": "US",\
"postalCode": "17901",\
"addressType": "commercial"\
},\
"returnToAddress": {\
"name": "Rod Runner",\
"phoneNumber": "865-433-9999",\
"phoneNumberCountryCode": "+2",\
"emailAddress": "rod@acme.com",\
"company": "ACME",\
"street1": "456 Main St.",\
"street2": "Suite 8",\
"city": "Albuquerque",\
"state": "NM",\
"countryCode": "US",\
"postalCode": "87121",\
"addressType": "commercial"\
},\
"fulfillmentContextId": "b4a3e646-4a10-4c7b-b974-1f115c9890c5",\
"requestFulfillmentContextIds": [\
"15daa625-aab7-4829-b224-3273bc89706d"\
],\
"originId": "e8b5552c-7119-4f72-a611-e1fb42645a86",\
"packagingType": {\
"packagingMaterial": "box",\
"packagingSizeName": "5x5x5 box",\
"linearDimensions": {\
"linearUnit": "in",\
"length": 5,\
"width": 5,\
"height": 5\
},\
"packagingWeight": {\
"weightUnit": "lb",\
"weight": 2.0\
}\
},\
"totalWeight": {\
"weightUnit": "lb",\
"weight": 10.0\
},\
"shipmentTags": ["PSFC", "Returns"],\
"carrierSelection": {\
"status": "success",\
"statusDetails": "success",\
"carrierSelectionId": "843ad336-3ca3-4b76-9bfa-06d99d9dd519",\
"shipiumShipmentId": "ba1919a1-1c9a-4f53-93a7-8af49213be7c",\
"partnerShipmentId": "myCustomPartnerShipmentId123",\
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",\
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",\
"serviceMethodIdentifier": "15daa625-aab7-4829-b224-3273bc89706d:ZmVkZXgtaG9tZS1kZWxpdmVyeS1zZXJ2aWNlLW1ldGhvZDo6N2JiYjY5NzMtYWVkYi00YTcwLWFjMDctMjIwY2JiMzdjYjIwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6ZThiNTU1MmMtNzExOS00ZjcyLWE2MTEtZTFmYjQyNjQ1YTg2Ojo",\
"carrier": "fedex",\
"carrierServiceMethodId": "fedex-home-delivery-service-method",\
"serviceMethodName": "FedEx Home Delivery",\
"totalCost": 4.2,\
"carrierCompareCost": 4.2,\
"carrierInvoiceCost": 4.2,\
"operationalCost": 4.2,\
"thirdPartyBilling": false,\
"carrierSelectionDateTime": "2019-10-30T17:23:28.722Z",\
"carrierZoneId": "fedex-zone-5"\
},\
"carrierLabel": {\
"shipiumShipmentId": "ba1919a1-1c9a-4f53-93a7-8af49213be7c",\
"carrierSelectionId": "843ad336-3ca3-4b76-9bfa-06d99d9dd519",\
"shipiumLabelId": "c20e715e-4b42-4e9a-8621-33a97ed89516",\
"status": "success",\
"statusDetails": "success",\
"effectiveShipDateTime": "2019-10-31T17:23:28.68Z",\
"labelCreationDateTime": "2019-10-30T17:23:31.207Z",\
"serviceMethodIdentifier": "15daa625-aab7-4829-b224-3273bc89706d:ZmVkZXgtaG9tZS1kZWxpdmVyeS1zZXJ2aWNlLW1ldGhvZDo6N2JiYjY5NzMtYWVkYi00YTcwLWFjMDctMjIwY2JiMzdjYjIwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6ZThiNTU1MmMtNzExOS00ZjcyLWE2MTEtZTFmYjQyNjQ1YTg2Ojo",\
"carrier": "fedex",\
"carrierServiceName": "FedEx Corporation Account - 2",\
"serviceMethodName": "FedEx Home Delivery",\
"carrierServiceMethodId": "fedex-home-delivery-service-method",\
"carrierShipmentId": "794624551550",\
"carrierTrackingId": "794624551550",\
"shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",\
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794624551550",\
"carrierLabelCurrencyCode": "usd",\
"carrierLabelPrice": 26.7,\
"billableWeight": {\
"weightUnit": "lb",\
"weight": 14.0\
},\
"documents": [\
{\
"labelExpiration": "2019-11-02T17:23:31.197106615Z",\
"labelFormat": "zpl",\
"labelProperties": {\
"height": 6.0,\
"width": 4.0,\
"linearUnits": "in",\
"dpi": 203,\
"labelOrientation": "rotate_180"\
},\
"labelImage": {\
"imageEncoding": "base64",\
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMTI0XkdCNzU1LDIsMl5GUwpeRk8xMiwzOTBeR0I3NzcsMiwyXkZTCl5GTzMyLDNeQWROLDAsMF5GV05eRkheRkRGUk9NOl5GUwpeRk8zMiwxOV5BZE4sMCwwXkZXTl5GSF5GRE1hYyBCcm93bl5GUwpeRk8zMiwzN15BZE4sMCwwXkZXTl5GSF5GREpHQyBTdG9yZF5GUwpeRk8zMiw1NV5BZE4sMCwwXkZXTl5GSF5GRDQyODUgQnVmb3JkIEh3eV5GUwpeRk8zMiw3M15BZE4sMCwwXkZXTl5GSF5GRF5GUwpeRk8zMiwxMDleQWROLDAsMF5GV05eRkheRkRVUyBeRlMKXkZPMjI0LDNeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8yOCw3NDJeQTBOLDI0LDI0XkZXTl5GSF5GRFRSSyNeRlMKXkZPMjgsODAwXkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPMTM2LDcxMl5BME4sMjcsMzZeRldOXkZIXkZEXkZTCl5GTzMyLDkxXkFkTiwwLDBeRldOXkZIXkZEQXRsYW50YSBHQSAzMDM0NV5GUwpeRk80NzgsM15BZE4sMCwwXkZXTl5GSF5GRFNISVAgREFURTogMThBUFIyNF5GUwpeRk80NzgsMTleQWROLDAsMF5GV05eRkheRkRBQ1RXR1Q6IDIuMDAgTEJeRlMKXkZPNDc4LDM3XkFkTiwwLDBeRldOXkZIXkZEQ0FEOiAwMDAwMDAwL1dTWEkzNjAwXkZTCl5GTzQ3OCw5MV5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzM5LDEzNl5BME4sMzksMzleRldOXkZIXkZESm9obiBEb2VeRlMKXkZPMzksMTc4XkEwTiwzOSwzOV5GV05eRkheRkReRlMKXkZPMzksMjIwXkEwTiwzOSwzOV5GV05eRkheRkQxMDAgTWFpbiBTdC5eRlMKXkZPMzksMjYyXkEwTiwzOSwzOV5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzM5LDM0N15BZE4sMCwwXkZXTl5GSF5GRCgyMDYpIDI2NS0yNzMzXkZTCl5GTzM5LDMwNF5BME4sNDMsNDBeRldOXkZIXkZER2VybWFudG93biBXSSA1MzAyMl5GUwpeRk83MTksMzA0XkEwTiw0Myw0MF5GV05eRkheRkQoVVMpXkZTCl5GTzY3Nyw0NjJeR0IxMDQsMTAsMTBeRlMKXkZPNjc3LDQ3Ml5HQjEwLDExMiwxMF5GUwpeRk83NzEsNDcyXkdCMTAsMTEyLDEwXkZTCl5GTzY3Nyw1ODReR0IxMDQsMTAsMTBeRlMKXkZPNDY0LC0tXkdCMiwxMjYsMl5GUwpeRk82ODcsNDgwXkEwTiwxMjgsMTM3XkZXTl5GSF5GREheRlMKXkZPNjU0LDQwMl5BME4sNDMsNTheRldOXkZIXkZERmVkRXheRlMKXkZPNjYzLDQ0OF5BYk4sMTEsN15GV05eRkheRkRIb21lIERlbGl2ZXJ5XkZTCl5GTzc5MSw0OTNeQTBOLDEzLDE4XkZXQl5GSF5GREoyNDIwMjQwNDA0MDF1dl5GUwpeRk85LDEzNl5BME4sMjEsMjFeRldOXkZIXkZEVE9eRlMKXkZPMjEsNDEyXkJZMiwyXkI3TiwxMCw1LDE0XkZIXkZXTl5GSF5GRFspPl8xRTAxXzFEMDI1MzAyMl8xRDg0MF8xRDgwNF8xRDc5NDYyNDU1MTU1MF8xREZERUdfMUQ4MDAwMzAyXzFEMTA5XzFEXzFEMS8xXzFEMi4wMExCXzFETl8xRDEwMCBNYWluIFN0Ll8xREdlcm1hbnRvd25fMURXSV8xREpvaG4gRG9lXzFFMDZfMUQxMFpHSDAwN18xRDEyWjIwNjI2NTI3MzNfMUQyMFpfMUNfMUQzMVo5NjIyMDgwNDMwMDA4MDAwMzAyOTAwNzk0NjI0NTUxNTUwXzFEOUtjZWxpYS10ZXN0aW5nXzFEXzFFXzA0XkZTCl5GTzI4LDgzN15BME4sMTA3LDk2XkZXTl5GSF5GRF5GUwpeRk8xMiw2ODFeR0I3NzcsMiwyXkZTCl5GTzQ5NCw4ODVeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83ODgsMjheQWJOLDExLDdeRldCXkZIXkZENTgzSjYvMEZFQy85QUUzXkZTCl5GTzk1LDc0Nl5BME4sNTMsNDBeRldOXkZIXkZEMDAwMCAwMDAwIDAwMDBeRlMKXkZPNDA5LDY5NV5BME4sNTEsMzheRldOXkZIXkZCMzkwLCwsUixeRkQgICAgICAgICAgICAgICAgICAgXkZTCl5GTzQwNCw3NDdeQTBOLDUxLDM4XkZXTl5GSF5GQjQwMCwsLFIsXkZEICAgICAgICAgICAgICAgICAgIF5GUwpeRk80MTMsNzk5XkEwTiw0MCw0MF5GV05eRkheRkIzODYsLCxSLF5GRCAgICAgICAgICAgICAgICBeRlMKXkZPNDk1LDg0MV5BME4sNDQsNDReRldOXkZIXkZCMjk4LCwsUixeRkQgICAgIDUzMDIyXkZTCl5GTzU3NCw5MDFeQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEICAgICAgXkZTCl5GTzY5NSw4ODVeQTBOLDQzLDQzXkZXTl5GSF5GQjEwMCwsLFIsXkZEICAgXkZTCl5GTzM5LDkyN15BME4sMjcsMzZeRldOXkZIXkZEMDAwMCAwMDAwIDAgKDAwMCAwMDAgMDAwMCkgMCAwMCAwMDAwIDAwMDAgMDAwMF5GUwpeRk83NSw5NjheQlkzLDJeQkNOLDIwMCxOLE4sTixOXkZXTl5GRD47OTYyMjA4MDQzMDAwODAwMDMwMjkwMDAwMDAwMDAwMDAwMF5GUwpeRk8xMzUsMTAyOF5BME4sMTI4LDEzN15GV05eRkheRkRTQU1QTEVeRlMKXkZPNDc4LDU1XkFkTiwwLDBeRldOXkZIXkZERElNTUVEOiAyNCBYIDEwIFggOCBJTl5GUwpeRk8zMjksMzQ5XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogQ0VMSUEtVEVTVElOR15GUwpeRk8zOSwzNjNeQWJOLDExLDdeRldOXkZIXkZESU5WOiBeRlMKXkZPMzksMzc3XkFiTiwxMSw3XkZXTl5GSF5GRFBPOiBeRlMKXkZPNDI5LDM3N15BYk4sMTEsN15GV05eRkheRkRERVBUOiBeRlMKXlBRMQpeWFoK"\
},\
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/ba1919a1-1c9a-4f53-93a7-8af49213be7c/carrierSelection/843ad336-3ca3-4b76-9bfa-06d99d9dd519/label/c20e715e-4b42-4e9a-8621-33a97ed89516/zpl"\
}\
]\
},\
"labelCreateParams": {\
"currencyCode": "usd",\
"labelFormats": [\
"zpl"\
],\
"eligibleForManifest": true,\
"includeLabelImagesInResponse": true,\
"customLabelEntries": {},\
"testMode": true,\
"contentDescription": "general merchandise"\
},\
"labelCostLineItems": [\
{\
"name": "Residential delivery surcharge",\
"currencyCode": "usd",\
"cost": 5.55\
},\
{\
"name": "FedEx Ground Fuel",\
"currencyCode": "usd",\
"cost": 1.4\
},\
{\
"name": "Base Charge",\
"currencyCode": "usd",\
"cost": 19.75\
}\
],\
"carrierLabelAugmentations": [],\
"manifestDetails": {\
"success": true,\
"interactionType": "manifest",\
"retryable": false\
},\
"originalLabelImageFromTheCarrier": {\
"imageEncoding": "base64",\
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QVzgwMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMTI0XkdCNzU1LDIsMl5GUwpeRk8xMiwzOTBeR0I3NzcsMiwyXkZTCl5GTzMyLDNeQWROLDAsMF5GV05eRkheRkRGUk9NOl5GUwpeRk8zMiwxOV5BZE4sMCwwXkZXTl5GSF5GRE1hYyBCcm93bl5GUwpeRk8zMiwzN15BZE4sMCwwXkZXTl5GSF5GREpHQyBTdG9yZF5GUwpeRk8zMiw1NV5BZE4sMCwwXkZXTl5GSF5GRDQyODUgQnVmb3JkIEh3eV5GUwpeRk8zMiw3M15BZE4sMCwwXkZXTl5GSF5GRF5GUwpeRk8zMiwxMDleQWROLDAsMF5GV05eRkheRkRVUyBeRlMKXkZPMjI0LDNeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8yOCw3NDJeQTBOLDI0LDI0XkZXTl5GSF5GRFRSSyNeRlMKXkZPMjgsODAwXkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPMTM2LDcxMl5BME4sMjcsMzZeRldOXkZIXkZEXkZTCl5GTzMyLDkxXkFkTiwwLDBeRldOXkZIXkZEQXRsYW50YSBHQSAzMDM0NV5GUwpeRk80NzgsM15BZE4sMCwwXkZXTl5GSF5GRFNISVAgREFURTogMThBUFIyNF5GUwpeRk80NzgsMTleQWROLDAsMF5GV05eRkheRkRBQ1RXR1Q6IDIuMDAgTEJeRlMKXkZPNDc4LDM3XkFkTiwwLDBeRldOXkZIXkZEQ0FEOiAwMDAwMDAwL1dTWEkzNjAwXkZTCl5GTzQ3OCw5MV5BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzM5LDEzNl5BME4sMzksMzleRldOXkZIXkZESm9obiBEb2VeRlMKXkZPMzksMTc4XkEwTiwzOSwzOV5GV05eRkheRkReRlMKXkZPMzksMjIwXkEwTiwzOSwzOV5GV05eRkheRkQxMDAgTWFpbiBTdC5eRlMKXkZPMzksMjYyXkEwTiwzOSwzOV5GV05eRkheRkQqKlRFU1QgTEFCRUwgLSBETyBOT1QgU0hJUCoqXkZTCl5GTzM5LDM0N15BZE4sMCwwXkZXTl5GSF5GRCgyMDYpIDI2NS0yNzMzXkZTCl5GTzM5LDMwNF5BME4sNDMsNDBeRldOXkZIXkZER2VybWFudG93biBXSSA1MzAyMl5GUwpeRk83MTksMzA0XkEwTiw0Myw0MF5GV05eRkheRkQoVVMpXkZTCl5GTzY3Nyw0NjJeR0IxMDQsMTAsMTBeRlMKXkZPNjc3LDQ3Ml5HQjEwLDExMiwxMF5GUwpeRk83NzEsNDcyXkdCMTAsMTEyLDEwXkZTCl5GTzY3Nyw1ODReR0IxMDQsMTAsMTBeRlMKXkZPNDY0LC0tXkdCMiwxMjYsMl5GUwpeRk82ODcsNDgwXkEwTiwxMjgsMTM3XkZXTl5GSF5GREheRlMKXkZPNjU0LDQwMl5BME4sNDMsNTheRldOXkZIXkZERmVkRXheRlMKXkZPNjYzLDQ0OF5BYk4sMTEsN15GV05eRkheRkRIb21lIERlbGl2ZXJ5XkZTCl5GTzc5MSw0OTNeQTBOLDEzLDE4XkZXQl5GSF5GREoyNDIwMjQwNDA0MDF1dl5GUwpeRk85LDEzNl5BME4sMjEsMjFeRldOXkZIXkZEVE9eRlMKXkZPMjEsNDEyXkJZMiwyXkI3TiwxMCw1LDE0XkZIXkZXTl5GSF5GRFspPl8xRTAxXzFEMDI1MzAyMl8xRDg0MF8xRDgwNF8xRDc5NDYyNDU1MTU1MF8xREZERUdfMUQ4MDAwMzAyXzFEMTA5XzFEXzFEMS8xXzFEMi4wMExCXzFETl8xRDEwMCBNYWluIFN0Ll8xREdlcm1hbnRvd25fMURXSV8xREpvaG4gRG9lXzFFMDZfMUQxMFpHSDAwN18xRDEyWjIwNjI2NTI3MzNfMUQyMFpfMUNfMUQzMVo5NjIyMDgwNDMwMDA4MDAwMzAyOTAwNzk0NjI0NTUxNTUwXzFEOUtjZWxpYS10ZXN0aW5nXzFEXzFFXzA0XkZTCl5GTzI4LDgzN15BME4sMTA3LDk2XkZXTl5GSF5GRF5GUwpeRk8xMiw2ODFeR0I3NzcsMiwyXkZTCl5GTzQ5NCw4ODVeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83ODgsMjheQWJOLDExLDdeRldCXkZIXkZENTgzSjYvMEZFQy85QUUzXkZTCl5GTzk1LDc0Nl5BME4sNTMsNDBeRldOXkZIXkZEMDAwMCAwMDAwIDAwMDBeRlMKXkZPNDA5LDY5NV5BME4sNTEsMzheRldOXkZIXkZCMzkwLCwsUixeRkQgICAgICAgICAgICAgICAgICAgXkZTCl5GTzQwNCw3NDdeQTBOLDUxLDM4XkZXTl5GSF5GQjQwMCwsLFIsXkZEICAgICAgICAgICAgICAgICAgIF5GUwpeRk80MTMsNzk5XkEwTiw0MCw0MF5GV05eRkheRkIzODYsLCxSLF5GRCAgICAgICAgICAgICAgICBeRlMKXkZPNDk1LDg0MV5BME4sNDQsNDReRldOXkZIXkZCMjk4LCwsUixeRkQgICAgIDUzMDIyXkZTCl5GTzU3NCw5MDFeQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEICAgICAgXkZTCl5GTzY5NSw4ODVeQTBOLDQzLDQzXkZXTl5GSF5GQjEwMCwsLFIsXkZEICAgXkZTCl5GTzM5LDkyN15BME4sMjcsMzZeRldOXkZIXkZEMDAwMCAwMDAwIDAgKDAwMCAwMDAgMDAwMCkgMCAwMCAwMDAwIDAwMDAgMDAwMF5GUwpeRk83NSw5NjheQlkzLDJeQkNOLDIwMCxOLE4sTixOXkZXTl5GRD47OTYyMjA4MDQzMDAwODAwMDMwMjkwMDAwMDAwMDAwMDAwMF5GUwpeRk8xMzUsMTAyOF5BME4sMTI4LDEzN15GV05eRkheRkRTQU1QTEVeRlMKXkZPNDc4LDU1XkFkTiwwLDBeRldOXkZIXkZERElNTUVEOiAyNCBYIDEwIFggOCBJTl5GUwpeRk8zMjksMzQ5XkFiTiwxMSw3XkZXTl5GSF5GRFJFRjogQ0VMSUEtVEVTVElOR15GUwpeRk8zOSwzNjNeQWJOLDExLDdeRldOXkZIXkZESU5WOiBeRlMKXkZPMzksMzc3XkFiTiwxMSw3XkZXTl5GSF5GRFBPOiBeRlMKXkZPNDI5LDM3N15BYk4sMTEsN15GV05eRkheRkRERVBUOiBeRlMKXlBRMQpeWFoK"\
},\
"saturdayDelivery": false,\
"deliverySignatureOption": "None",\
"forceThirdPartyBilling": false,\
"referenceIdentifier": "PSFC-2478",\
"createdWithVersion": "v2",\
"details": {\
"fulfillmentContextDetailsSearch": {\
"country": "US",\
"fulfillmentType": "customer",\
"postalCode": "17901",\
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",\
"includeSimulation": false,\
"fulfillmentContextIds": [\
"15daa625-aab7-4829-b224-3273bc89706d"\
]\
},\
"generateLabel": true,\
"includeEvaluatedServiceMethodsInResponse": false,\
"labelParameters": {\
"currencyCode": "usd",\
"labelFormats": [\
"zpl"\
],\
"eligibleForManifest": true,\
"includeLabelImagesInResponse": true,\
"customLabelEntries": {},\
"testMode": true,\
"contentDescription": "general merchandise"\
},\
"carrierServiceMethodAllowList": [],\
"includeInjectionProfiles": false,\
"injectionParameters": [],\
"simulation": false,\
"inlineReturnsLabel": {\
"partnerShipmentId": "myCustomPartnerShipmentId123",\
"returnToAddress": {\
"countryCode": "US",\
"postalCode": "17901",\
"addressType": "commercial",\
"city": "Pottsville",\
"company": "Sell It",\
"emailAddress": "rodrunner@sellit.com",\
"name": "Ro Drunner",\
"phoneNumber": "5555555555",\
"state": "PA",\
"street1": "401 Centre St."\
},\
"returnToContactInfo": {\
"contactName": "Ro Drunner",\
"phoneNumber": "5555555555",\
"phoneNumberCountryCode": "1",\
"email": "rodrunner@sellit.com"\
},\
"fulfillmentContextId": "b4a3e646-4a10-4c7b-b974-1f115c9890c5",\
"inlineReturnReferenceIdentifier": "ReturnLane1",\
"inlineReturnReferenceIdentifier2": "LVO-34",\
"saturdayDelivery": true\
},\
"returnsContentDescription": "general merchandise"\
}\
}\
```\
\
# Generate a return label independent of shipment label generation [Skip link to Generate a return label independent of shipment label generation](https://docs.shipium.com/docs/return-labels\#generate-a-return-label-independent-of-shipment-label-generation)\
\
The [Return Label API](https://docs.shipium.com/docs/return-label-api) documentation includes required and optional fields for generating a return label independently. The sample call request and response are included below.\
\
## Printerless labels for returns [Skip link to Printerless labels for returns](https://docs.shipium.com/docs/return-labels\#printerless-labels-for-returns)\
\
For select carriers, you can request printerless labels that generate QR codes instead of traditional shipping labels. Customers can scan these QR codes at carrier locations without printing a physical label. Printerless labels are currently supported for Canada Post returns.\
\
**How to request.** Include "printerless" in the `labelFormats` array and provide the `printerlessParameters` configuration. You can request both traditional and printerless formats in the same call (e.g., \["zpl", "printerless"\]).\
\
**What you receive.** The response includes a base64-encoded image of the QR code and the URL encoded within it. The URL value can be used to generate your own QR code if needed. For more details and examples, you can refer to the [Return Label API](https://docs.shipium.com/docs/return-label-api) documentation.\
\
## Example cURL request [Skip link to Example cURL request](https://docs.shipium.com/docs/return-labels\#example-curl-request-1)\
\
The request looks very similar to a [carrier shipment label](https://docs.shipium.com/docs/carrier-shipment-label-flow) request. You pass information about the origin address and destination address, as shown in the cURL request below:\
\
cURL\
\
```curl\
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 [Skip link to Example request body](https://docs.shipium.com/docs/return-labels\#example-request-body-1)\
\
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](https://docs.shipium.com/docs/label-customization). The [Return Label API](https://docs.shipium.com/docs/return-label-api) documentation and the [Return Label API Reference](https://docs.shipium.com/reference/returnslabelcreatev1) provide details about information to include in the API request.\
\
JSON\
\
```json\
{\
"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 [Skip link to Example response body](https://docs.shipium.com/docs/return-labels\#example-response-body-1)\
\
The return label response is almost identical to the response returned by [carrier shipment label](https://docs.shipium.com/docs/shipment-label-api), though with some differences as carrier costing does not occur for return labels.\
\
JSON\
\
```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"\
}\
```\
\
# Retrieve previously created labels [Skip link to Retrieve previously created labels](https://docs.shipium.com/docs/return-labels\#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\
\
```curl\
curl --request GET \\
--url </api/v1/deliveryexperience/customerreturn/label/{returnLabelId}\
--header 'accept: application/json' \\
--header $AUTHSTRING \\
--header 'content-type: application/json'\
```\
\
> 📘\
>\
> ### More information on the API responses [Skip link to More information on the API responses](https://docs.shipium.com/docs/return-labels\#more-information-on-the-api-responses)\
>\
> As with all Shipium API responses, this API follows the [API Response Codes](https://docs.shipium.com/docs/api-response-codes) standards unless otherwise specified.\
\
# Resources [Skip link to Resources](https://docs.shipium.com/docs/return-labels\#resources)\
\
Your Shipium team member is available to help along the way. However, you might find these resources helpful:\
\
- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)\
\
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)\
\
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)\
\
\
Updated 4 months ago\
\
* * *\
\
Did this page help you?\
\
Yes\
\
No\
\
Copy Page\
\
🦉\
\
# Recipe Title\
\
Recipe Description\
\
x\
\
```\
\
```\
\
1{"success":true}\
\
## Are you sure?