Return Shipping Labels

ShipEngine allows you to generate and print return labels to include in your shipments to customers. This allows your customers to send back items for exchange or refund without having to deal with printing shipping labels.

API Endpoints

Return labels can be created via the following endpoints.

  • /v1/labels with the is_return_label property set to true
  • /v1/labels/:label_id/return, automatically generates a return label with the same carrier and carrier service as the outbound label.

Label Charges

When creating a request to create a return label, you will need to specify a charge_event to indicate when you should be charged for the return label.

You may be charged on_creation (at the time the label is created), on_carrier_acceptance (when the label is scanned by the carrier), or use the carrier_default to use the carrier's default charge behavior.

The on_carrier_acceptance option is useful for overriding the carrier's default behavior, but you must have the carrier enable this on your account before sending this option in your request. If you send a request with charge_event: on_carrier_acceptance and the carrier has not enabled this feature on your account, you will get an error.

Warning

Carrier Lead Times

Please note that it can take the carrier 3-4 weeks to update your account, so you should start this process with the carrier as early as possible if you wish to use this feature.

Note

Endicia Not Supported

Creating labels that are charged on carrier acceptance is not supported directly for Endicia. You may only use this feature with Endicia accounts offered through Stamps.com.

Request Properties

Property Type Description
is_return_label boolean Indicates if the label should be created as a return label.
rma_number string An optional "Return Merchandise Authorization" code, which can be used to link the return label to your system.
outbound_label_id string The label_id of the original (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.

carrier_default: Use the carrier's default charge behavior.

on_creation: You are charged for the label when it is created. This is the default behavior for Stamps.com (USPS).

on_carrier_acceptance: You are not charged for the label until it is actually used (a.k.a. "scan-based labels"). This is the default behavior for most carriers.

Note

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

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.

Examples

POST /v1/labels/

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.

Info outbound_label_id will only be populated when creating a return label via the /labels/:label_id/return endpoint.

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

Return Label

POST /v1/labels/:label_id/return

This endpoint provides a convenient way to create a return label without having to specify all the same shipment and package information over again. It just uses all the same values as the original label, but reverses the ship_from and ship_to addresses.

Note The v1/labels/:label_id/return endpoint makes the following assumption about the generated return label:

  • No address validation will be performed.
  • The same carrier and service type will be used as the original label.
POST /v1/labels/__YOUR_LABEL_ID_HERE__/return HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
{
  "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
    }
  }]
}