> 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/get-return-request-list.md).

# Get Return Request List

### Endpoint

```http
GET /open-api/v1/return-requests
```

### Description

Use this API to page through return requests for the authenticated shop.

It can be used for synchronization, reconciliation, or troubleshooting.

### Query Parameters

| Parameter          | Type  | Required | Description                                    |
| ------------------ | ----- | -------- | ---------------------------------------------- |
| `page`             | int   | No       | Page number. Default is `1`.                   |
| `limit`            | int   | No       | Page size. Default is `50`, maximum is `50`.   |
| `created_at_start` | int64 | No       | Created time start. Unix timestamp in seconds. |
| `created_at_end`   | int64 | No       | Created time end. Unix timestamp in seconds.   |

### Request Example

```bash
curl "$BASE_URL/open-api/v1/return-requests?page=1&limit=50&created_at_start=1710000000&created_at_end=1710086400" \
  -H "X-RETURN-SHOP-DOMAIN: demo.myshopify.com" \
  -H "X-RETURN-ACCESS-TOKEN: your-token"
```

### Success Response

```json
{
    "code": 1000,
    "msg": "success",
    "data": {
        "list": [
            {
                "request_id": 10006,
                "rma": "RMA-10006",
                "order_no": "#1001",
                "order_id": 501,
                "shopify_order_id": 450789469,
                "shopify_return_id": 9988,
                "return_order_no": "RET-1",
                "type": 1,
                "status": 2,
                "status_name": "approved",
                "customer_email": "buyer@example.com",
                "customer_name": "Jane Buyer",
                "shipping_method_id": 1,
                "solution_id": 3,
                "is_select_shipping_method_later": 0,
                "total_quantity": 2,
                "currency": "USD",
                "created_at": 1710000000,
                "updated_at": 1710000100,
                "items": [
                    {
                        "item_id": 11163,
                        "line_item_id": 16663148658944,
                        "shopify_product_id": 9490204426496,
                        "shopify_variant_id": 48858322043136,
                        "product_name": "The Complete Snowboard",
                        "variant_name": "Dawn",
                        "sku": "",
                        "return_quantity": 1,
                        "price": 699.95,
                        "reason_id": 6698,
                        "reason_text": "test",
                        "reason_description": "111",
                        "proof_images": [
                            "https://return-cdn.parcelpanel.com/return-test/758/c/20260826/18cf4bee5dca6d4897bcbf5890c7ac44.png"
                        ]
                    }
                ],
                "labels": [
                    {
                        "adjustments": [
                            {
                                "amount": 3.5,
                                "reason": "Shipping Charge Correction: Billed weight exceeds declared weight. Declared Weight (lb): 20.0, Billed Weight (lb): 25.0",
                                "invoice_date": 1785348459,
                                "paid_at": 1785839946
                            },
                            {
                                "amount": 2.75,
                                "reason": "Additional Handling Charge - Weight",
                                "invoice_date": 1785348460,
                                "paid_at": 1785839946
                            },
                            {
                                "amount": 2,
                                "reason": "Fuel Surcharge (Ground)",
                                "invoice_date": 1785348461,
                                "paid_at": 1785839946
                            }
                        ],
                        "tracking_number": "9200000000000000111299",
                        "label_fee": 18.16,
                        "adjustment_fees": 8.25,
                        "currency": "USD",
                        "is_return": true
                    }
                ]
            }
        ],
        "page_info": {
            "total": 1,
            "per_page": 50,
            "current_page": 1,
            "last_page": 1
        }
    }
}
```

### Response Fields

| Field                             | Description                                                         |
| --------------------------------- | ------------------------------------------------------------------- |
| `request_id`                      | Internal return request ID                                          |
| `rma`                             | RMA number                                                          |
| `order_no`                        | Original order number                                               |
| `order_id`                        | Internal order record ID                                            |
| `shopify_order_id`                | Shopify order ID                                                    |
| `shopify_return_id`               | Shopify return ID                                                   |
| `return_order_no`                 | Shopify return name                                                 |
| `type`                            | Request type                                                        |
| `status`                          | Return request status                                               |
| `status_name`                     | Status name                                                         |
| `customer_email`                  | Customer email                                                      |
| `customer_name`                   | Customer name                                                       |
| `shipping_method_id`              | Current shipping method ID                                          |
| `solution_id`                     | Return solution ID                                                  |
| `is_select_shipping_method_later` | Whether the return was approved with shipping method selected later |
| `total_quantity`                  | Total return quantity                                               |
| `currency`                        | Currency                                                            |
| `items`                           | Return Product Items                                                |
| `labels`                          | Shipping labels with label fees and billing adjustments             |
| `labels.tracking_number`          | Tracking number                                                     |
| `labels.label_fee`                | Shipping label fee                                                  |
| `labels.adjustment_fees`          | Total billing adjustment fees                                       |
| `labels.currency`                 | Currency                                                            |
| `labels.is_return`                | Whether this is a return shipping label                             |
| `labels.tracking_number`          | Billing adjustment details                                          |
| `labels.adjustments.amount`       | Adjustment amount                                                   |
| `labels.adjustments.reason`       | Reason for the billing adjustment                                   |
| `labels.adjustments.invoice_date` | Invoice time, Unix timestamp in seconds                             |
| `labels.adjustments.paid_at`      | Payment time, Unix timestamp in seconds                             |
| `labels.created_at`               | Created time, Unix timestamp in seconds                             |
| `labels.updated_at`               | Updated time, Unix timestamp in seconds                             |
| `created_at`                      | Created time, Unix timestamp in seconds                             |
| `updated_at`                      | Updated time, Unix timestamp in seconds                             |

### Notes

* Results are sorted by `created_at DESC, id DESC`.
* If `limit` is greater than `50`, Return will use `50`.
* If `created_at_start` is greater than `created_at_end`, the API returns a parameter error.