> For the complete documentation index, see [llms.txt](https://parcelwill-returns.gitbook.io/help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parcelwill-returns.gitbook.io/help-center/openapi/create-return-label.md).

# Create Return Label

### Endpoint

```http
POST /open-api/v1/return-labels
```

### Description

Use this API to send merchant-created return labels back to Return.

The API uses rma to identify the return request.

Pending review -> The return request will be automatically approved and the provided return label(s) will be attached. Approved (no existing return label) -> The provided return label(s) will be saved. Approved (existing return label) -> The API returns an error and does not overwrite the existing label.

A return is considered to have an existing return label when the webhook payload contains "return\_status": "Approved" and return\_shipping\_method.tracking\_no is not empty.

### Request Example

```bash
curl -X POST "$BASE_URL/open-api/v1/return-labels" \
  -H "Content-Type: application/json" \
  -H "X-RETURN-SHOP-DOMAIN: demo.myshopify.com" \
  -H "X-RETURN-ACCESS-TOKEN: your-token" \
  -d '{
    "rma": "RMA-10006",
    "return_address_id": 1252,
    "return_label_type": 2,
    "shipping_method_id": 1,
    "act_fee": 0,
    "label_list": [
      {
        "tracking_number": "1111222",
        "shipping_carrier": "USPS",
        "is_label_url": 1,
        "return_label_link": "https://example.com/label/1111222.pdf"
      }
    ]
  }'
```

### Body Parameters

| Field                | Type   | Required    | Description                                                                            |
| -------------------- | ------ | ----------- | -------------------------------------------------------------------------------------- |
| `rma`                | string | Yes         | RMA from webhook payload                                                               |
| `return_address_id`  | int64  | Recommended | Return address ID. If omitted, Return will try to use the shop default return address. |
| `return_label_type`  | int    | Recommended | Must be `2`, meaning merchant-created manual label                                     |
| `shipping_method_id` | int    | No          | Defaults to `1`                                                                        |
| `act_fee`            | number | No          | Actual label fee                                                                       |
| `label_list`         | array  | Yes         | Label list. Must contain at least one item.                                            |

### label\_list Parameters

| Field               | Type   | Required                       | Description                                                |
| ------------------- | ------ | ------------------------------ | ---------------------------------------------------------- |
| `tracking_number`   | string | Yes                            | Tracking number. Spaces and `-` will be removed by Return. |
| `shipping_carrier`  | string | Yes                            | Carrier name                                               |
| `is_label_url`      | int    | Yes                            | `1` means label URL, `0` means uploaded label file         |
| `return_label_link` | string | Required when `is_label_url=1` | Label URL                                                  |
| `return_label`      | string | Required when `is_label_url=0` | Uploaded label file URL                                    |
| `return_label_file` | object | Required when `is_label_url=0` | Uploaded label file info. `name` is required.              |

### URL Label Example

```json
{
  "tracking_number": "1111222",
  "shipping_carrier": "USPS",
  "is_label_url": 1,
  "return_label_link": "https://example.com/label/1111222.pdf"
}
```

### Uploaded File Label Example

```json
{
  "tracking_number": "1111222",
  "shipping_carrier": "USPS",
  "is_label_url": 0,
  "return_label": "https://example.com/uploaded/label.pdf",
  "return_label_file": {
    "name": "label.pdf",
    "type": "application/pdf",
    "type_default": "pdf",
    "size": 12345
  }
}
```

### Business Logic

| Current Return Status | System Action                                  | Response `operation` |
| --------------------- | ---------------------------------------------- | -------------------- |
| Pending review        | Approve the return request and save label data | `approve`            |
| Approved              | Update shipping and save label data            | `update_shipping`    |
| Other statuses        | Reject the request                             | -                    |

### Important Notes

* `return_label_type` should always be `2`.
* The API currently supports Pending review and Approved return requests only.
* For Approved returns, if tracking already exists, the API returns an error and does not overwrite the old label.
* `tracking_number` must be unique after normalization.
* `111-222` and `111222` are treated as the same tracking number.
* The normalized tracking number cannot exceed 100 characters.

### Success Response: Pending Review

```json
{
  "code": 1000,
  "msg": "success",
  "data": {
    "request_id": 10006,
    "rma": "RMA-10006",
    "operation": "approve",
    "tracking_numbers": ["1111222"]
  }
}
```

### Success Response: Approved

```json
{
  "code": 1000,
  "msg": "success",
  "data": {
    "request_id": 10006,
    "rma": "RMA-10006",
    "operation": "update_shipping",
    "tracking_numbers": ["1111222"],
    "tracking_ids": {
      "1111222": 98765
    }
  }
}
```

### Errors Message

| Error                                                                    | Description                                   |
| ------------------------------------------------------------------------ | --------------------------------------------- |
| `rma is required`                                                        | Missing `rma`                                 |
| `return_label_type must be 2`                                            | `return_label_type` is not `2`                |
| `label_list is required`                                                 | Missing or empty `label_list`                 |
| `tracking_number and shipping_carrier are required`                      | Missing tracking number or carrier            |
| `tracking_number in label_list must be unique`                           | Duplicate tracking number after normalization |
| `return_label_link is required when is_label_url is 1`                   | Missing label URL                             |
| `return_label and return_label_file are required when is_label_url is 0` | Missing uploaded label file data              |
| `return tracking already exists`                                         | Approved return already has tracking          |