# Return Labels With ShipStation API, you can create return labels to include in your shipments to customers or send to them later to facilitate a return. You have two methods for creating return labels using ShipStation API: * `/v1/labels`: Create a label in the usual way but set the `is_return_label` property set to `true`. * `/v1/labels/:label_id/return`: Create return label using the `label_id` of a previously created label. ## Requirements * Make sure the carrier and service you wish to use supports return labels (not all carriers and services can be used for return labels). * Returns are currently only supported for domestic shipments. You cannot create return labels for international shipments at this time. * You'll need to specify a value for the `charge_event` property to indicate when you should be charged for the return label. Depending on which method you use, there will be some additional requirements for the request headers and body schema. ## Specify Charge Event When creating a return label, you will need to specify a `charge_event` to indicate when you should be charged for the return label. | Charge Event Type | Description | | --- | --- | | `on_creation` | Charge for the label at the time of label creation. This is the default behavior for USPS (Stamps.com) and ShipStation Carriers. | | `on_carrier_acceptance` | Charge for the label when it is scanned by the carrier. This is the default behavior for most other carriers. | | `carrier_default` | Use the carrier's default charge behavior. | ### Unused Return Labels If you create a return label that is charged on creation and it goes unused, you will need to [void the label](/apis/shipengine/docs/labels/voiding) if you wish to get a refund for that label. For other charge event types you are not charged for the label unless it is used, so it won't be necessary to void those labels. ### About the On Carrier Acceptance Option The `on_carrier_acceptance` option is useful for overriding the carrier's default behavior if their default is to charge on label creation. You typically must have the carrier enable this on your account before setting this option in your requests. If you send a request with `charge_event: on_carrier_acceptance` and the carrier has not enabled this feature on your account, you will receive an error. * It can take the carrier 3-4 weeks to update your account to use the `on_carrier_acceptance` option, so you should start this process with the carrier as early as possible if you wish to use this feature. * If you wish to use the `on_carrier_acceptance` option with Endicia, you must have Endicia enable the Pay-on-Use-Returns option for your Endicia account. ## /v1/labels/ Method **POST /v1/labels/** This method is most commonly used when you wish to create a return label to include with an outgoing shipment. With this method, you'll create a label like you usually would, but since this is a return label the `ship_from` address should be your customer's address and the `ship_to` address should be your warehouse or return center. You'll also add the following properties to your request: | Property | Type | Description | | --- | --- | --- | | `is_return_label` | *boolean* | Set to `true` to indicate the label should be created as a return label. | | `rma_number` | *string* | An optional "Return Merchandise Authorization" code, which you can use to link the return label to your system. | | `outbound_label_id` | *string* | The `label_id` of the outgoing label that this return label is for. This associates the two labels together, which is required by some carriers. | | `charge_event` | *enumerated string* | Determines when you are charged for the label. | > **NOTE:** The `is_return_label` property is only valid for the `/v1/labels` endpoint. It is not currently supported for the `/v1/labels/rates` or `/v1/labels/shipment` endpoints. ### Example Request & Response ```http POST /v1/labels HTTP/1.1 Host: api.shipengine.com API-Key: __YOUR_API_KEY_HERE__ Cache-Control: no-cache Content-Type: application/json { "is_return_label": true, "rma_number": "mVRUr79663", "outbound_label_id": "se-4567890", "charge_event": "carrier_default", "shipment": { "service_code": "usps_priority_mail", "ship_to": { "name": "John Doe", "phone": "111-111-1111", "company_name": "Example Corp.", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "ship_from": { "name": "Amanda Miller", "phone": "555-555-5555", "address_line1": "525 S Winchester Blvd", "city_locality": "San Jose", "state_province": "CA", "postal_code": "95128", "country_code": "US", "address_residential_indicator": "yes" }, "packages": [ { "weight": { "value": 1.0, "unit": "ounce" } } ] } } ``` **Response** ```json { "label_id": "se-136285644", "status": "completed", "shipment_id": "se-266656884", "ship_date": "2018-08-08T00:00:00Z", "created_at": "2018-08-08T15:23:07.727Z", "shipment_cost": { "currency": "usd", "amount": 7.13 }, "insurance_cost": { "currency": "usd", "amount": 0 }, "tracking_number": "9405511899223189314121", "is_return_label": true, "rma_number": "mVRUr79663", "outbound_label_id": "se-4567890", "charge_event": "carrier_default", "is_international": false, "batch_id": "", "carrier_id": "se-143975", "service_code": "usps_priority_mail", "package_code": "package", "voided": false, "voided_at": null, "label_format": "pdf", "label_layout": "4x6", "trackable": true, "carrier_code": "stamps_com", "tracking_status": "in_transit", "label_download": { "pdf": "https://api.shipengine.com/v1/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.pdf", "png": "https://api.shipengine.com/v1/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.png", "zpl": "https://api.shipengine.com/v1/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.zpl", "href": "https://api.shipengine.com/v1/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.pdf" }, "form_download": null, "insurance_claim": null, "packages": [ { "package_code": "package", "weight": { "value": 1, "unit": "ounce" }, "dimensions": { "unit": "inch", "length": 0, "width": 0, "height": 0 }, "insured_value": { "currency": "usd", "amount": 0 }, "tracking_number": "9405511899223189314121", "label_messages": { "reference1": null, "reference2": null, "reference3": null } } ] } ``` ## /v1/labels/:label_id/return Method **POST /v1/labels/:label_id/return** This method is a convenient way to create a return label without specifying all the same shipment and package information over again. It's typically used when a return request is made after the customer has received their shipment. This method also includes the `display_scheme` property, which allows you to create [paperless labels](/apis/shipengine/docs/labels/paperless) with supported carriers and services. When using this method, the return label uses all the same values as the original label (including the carrier and service) and reverses the `ship_from` and `ship_to` addresses. It's also important to note that no address validation will occur with this method (since it is assumed the original label already passed address validation). The following properties are available to add to the request body (but are not required): | Property | Type | Description | | --- | --- | --- | | `charge_event` | *enumerated string* | Determines when you are charged for the label. If not specified, the charge event will be `carrier_default`. | | `label_layout` | *enumerated string* | `4x6` or `letter`. Allows you to set the size the label file will be returned in. If using `letter`, the `label_format` must be set to `pdf`. | | `label_format` | *enumerated string* | `pdf`, `png`, `zpl`. The file format that you want the label to be in. `pdf` is the most widely supported by carriers. | | `label_download_type` | The file format that you want the label to be in. | `url` (default if left unspecified) - the response will include a URL to download the label and will be valid for 90 days. `inline` - the response will include a Base64-encoded label as part of the response. | | `display_schema` | *enumerated string* | The display format that the label should be shown in. `label` (default), `paperless`, `label_and_paperless`. | | `label_image_id` | *string* | The label image resource that was used to create a custom label image. | ### Example Request & Response ```http POST /v1/labels/se-21723/return HTTP/1.1 Host: api.shipengine.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response** ```json { "label_id": "se-21780", "status": "completed", "shipment_id": "se-1026409", "ship_date": "2019-05-30T00:00:00Z", "created_at": "2019-05-30T21:05:22.5920561Z", "shipment_cost": { "currency": "usd", "amount": 3.22 }, "insurance_cost": { "currency": "usd", "amount": 0 }, "tracking_number": "9400111899564765837649", "is_return_label": true, "rma_number": null, "outbound_label_id": "se-21723", "charge_event": "carrier_default", "is_international": false, "batch_id": "", "carrier_id": "se-19709", "service_code": "usps_first_class_mail", "package_code": "package", "voided": false, "voided_at": null, "label_format": "pdf", "label_layout": "4x6", "trackable": true, "carrier_code": "stamps_com", "tracking_status": "in_transit", "label_download": { "pdf": "http://localhost:55163/v1/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.pdf", "png": "http://localhost:55163/v1/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.png", "zpl": "http://localhost:55163/v1/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.zpl", "href": "http://localhost:55163/v1/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.pdf" }, "form_download": null, "insurance_claim": null, "packages": [{ "package_code": "package", "weight": { "value": 6, "unit": "ounce" }, "dimensions": { "unit": "inch", "length": 0, "width": 0, "height": 0 }, "insured_value": { "currency": "usd", "amount": 0 }, "tracking_number": "9400111899564765837649", "label_messages": { "reference1": null, "reference2": null, "reference3": null } }] } ```