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 with ShipStation API:
/v2/labels: Create a label in the usual way but set theis_return_labelproperty set totrue./v2/labels/:label_id/return: Create return label using thelabel_idof 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_eventproperty 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 goes unused, you will need to void the label 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_acceptanceoption, 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_acceptanceoption with Endicia, you must have Endicia enable the Pay-on-Use-Returns option for your Endicia account.
/v2/labels/ Method
POST /v2/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. |
The is_return_label property is only valid for the /v2/labels endpoint. It is not currently supported for the /v2/labels/rates or /v2/labels/shipment endpoints.
Sample Request & Response
POST /v2/labels HTTP/1.1 Host: api.shipstation.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
{ "label_id": "se-136285644", "status": "completed", "shipment_id": "se-266656884", "ship_date": "2024-08-08T00:00:00Z", "created_at": "2024-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.shipstation.com/v2/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.pdf", "png": "https://api.shipstation.com/v2/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.png", "zpl": "https://api.shipstation.com/v2/downloads/6/qmxE48xI5Uy1_Ax1W4vamg/label-136285644.zpl", "href": "https://api.shipstation.com/v21/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 } } ] }
/v2/labels/:label_id/return Method
POST /v2/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 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 | 4x6orletter. Allows you to set the size the label file will be returned in. If using letter, the label_formatmust be set topdf`. |
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 provided in. label (default), paperless, label_and_paperless, qr_code (deprecated), label_and_qr_code (deprecated). |
label_image_id | string | The label image resource that was used to create a custom label image. |
Sample Request & Response
POST /v2/labels/se-21723/return HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__
Response
{ "label_id": "se-21780", "status": "completed", "shipment_id": "se-1026409", "ship_date": "2024-05-30T00:00:00Z", "created_at": "2024-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/v2/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.pdf", "png": "http://localhost:55163/v2/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.png", "zpl": "http://localhost:55163/v2/downloads/1/Mlek_uOx5kiDTfbq4e0Rmw/label-21780.zpl", "href": "http://localhost:55163/v2/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 } }] }