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. If you create a return label that is charged on creation, and it goes unused, you will need to void the label to get a refund for that label. For all other cases, you are not charged, so. it will be unnecessary to void a label.

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.

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.

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.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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"
        }
      }
    ]
  }
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
  "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
      }
    }
  ]
}

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.

Example Request

1
2
3
POST /v1/labels/__YOUR_LABEL_ID_HERE__/return HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
  "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
    }
  }]
}