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.

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.

Return shipping fields

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/

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

  curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "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"
        }
      }
    ]
  }
}'
  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.
curl -iX POST https://api.shipengine.com/v1/labels/__YOUR_LABEL_ID_HERE__/return \
-H '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
    }
  }]
}