Return Shipping Labels

You may want to be able to generate a return label for your customers to send back items they need for exchange, refunds, or additional services. ShipEngine allows you to indicate that you are creating a return label by setting is_return_label to true.

API Endpoint

POST /v1/labels/

field value description
is_return_label boolean indicates if the label should be created as a return label.
rma_number string (Optional) "Return Merchandise Authorization" value, used to externally reference a return.

warning

Only valid with the 'v1/labels' endpoint

The is_return_label field can only be used for the /v1/labels endpoint. It is not currently supported for the /v1/labels/rates or /v1/labels/shipment endpoints.

warning

International Return Labels are not supported

ShipEngine currently is unable to support return label creation for international shipment configurations. Only domestic return labels are possible.

warning

Test return labels are not supported.

You're not currently able to create test return labels. Be aware that creating a return label can result in charges from any carrier who generates pre-paid labels. Please see your carrier's refund policies for more information and be sure to void the label before your carrier's refund policy period ends.\n\nInstructions for voiding a label can be found on our Void a Label guide.

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Shippy",
      "phone": "512-485-4282",
      "company_name": "ShipEngine",
      "address_line1": "3800 N. Lamar Blvd.",
      "address_line2": "Suite 220",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Mickey and Minnie Mouse",
      "phone": "+1 (714) 781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  },
  "test_label": false,
  "is_return_label": true,
  "rma_number": "mVRUr79663"
}'
POST /v1/labels HTTP/1.1
host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
cache-control: no-cache
Content-Type: application/json
content-length: 1054

{
  "is_return_label": true,
  "rma_number": "mVRUr79663",
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Shippy",
      "phone": "512-485-4282",
      "company_name": "ShipEngine",
      "address_line1": "3800 N. Lamar Blvd.",
      "address_line2": "Suite 220",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Mickey and Minnie Mouse",
      "phone": "+1 (714) 781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  }
}

Example Response

{
  "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",
  "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
      }
    }
  ]
}

Return Label