**版本：202601**

# 查询退款记录列表

**GET** `/openapi/2026-01/orders/refund_records`

返回所有订单的退款记录，支持按订单 ID、退款记录 ID、状态、排序字段与方向、 创建/更新时间范围过滤，使用 cursor 分页。

## 请求

**Query参数**

- `cursor` string

  分页游标
- `page_size` int32

  每页记录数（1-100，默认 10）
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `order_ids` string[]

  按订单 ID 过滤，最多支持 10 个。 示例：?order\_ids=1001&order\_ids=1002
- `refund_order_ids` string[]

  按退款记录 ID 过滤，最多支持 20 个。 示例：?refund\_order\_ids=2001&refund\_order\_ids=2002
- `refund_statuses` string[]

  按退款状态过滤。

  *   pending: 退款中。
  *   finished: 退款完成。
  *   failed: 退款失败。 示例：?refund\_statuses=pending&refund\_statuses=finished
- `sort_by` string

  排序字段：

  *   `created_at`: 按创建时间排序
  *   `updated_at`: 按更新时间排序
- `sort_direction` string

  排序方向：

  *   `desc`: 降序
  *   `asc`: 升序
- `created_at_start` string

  按创建时间过滤的起始值（如 2018-11-02T12:30:10Z）
- `created_at_end` string

  按创建时间过滤的结束值（如 2018-11-02T12:30:10Z）
- `updated_at_start` string

  按最后更新时间过滤的起始值（如 2018-11-02T12:30:10Z）
- `updated_at_end` string

  按最后更新时间过滤的结束值（如 2018-11-02T12:30:10Z）

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `records` object[]

    退款记录列表

    *   Array \[

    - `id` string

      退款记录 ID
    - `refund_price` string

      退款金额
    - `refund_shipping` string

      运费退款信息
    - `refund_shipping_tax` string

      退款运费税金额
    - `refund_method` string

      退款方式
    - `refund_status` string

      退款状态：

      *   `pending`: 退款中
      *   `finished`: 退款完成
      *   `failed`: 退款失败
    - `note` string

      备注
    - `created_at` string

      退款记录创建时间（如 2018-11-02T12:30:10Z）
    - `updated_at` string

      退款记录最后更新时间（如 2018-11-02T12:30:10Z）
    - `refund_line_items` object[]

      退款行项目列表

      *   Array \[

      - `line_item_id` string

        被退款的订单商品行 ID
      - `refund_quantity` int32

        退款数量
      - `tax` string

        税费
      - `discount` string

        折扣信息
      - `sub_total` string

        小计金额
      - `total` string

        总计
      - `delete_quantity` int32

        删除数量
      *   \]
    - `payment_details` object[]

      支付详情列表

      *   Array \[

      - `id` string

        退款记录 ID
      - `payment_line_id` string

        支付行 ID
      - `payment_channel` string

        支付渠道
      - `payment_method` string

        支付方式
      - `refund_price` string

        退款金额
      - `refund_status` string

        退款状态：

        *   `pending`: 退款中
        *   `finished`: 退款完成
        *   `failed`: 退款失败
      - `finished_at` string

        退款完成时间
      *   \]
    - `additional_total` string

      附加总额
    - `additional_prices` object[]

      附加价格列表

      *   Array \[

      - `name` string

        附加费用名称
      - `price` string

        附加费用金额
      - `biz_id` string

        业务 ID
      - `fee_title` string

        自定义收费名称
      *   \]
    - `refund_tip` string

      小费退款金额
    - `order_id` string

      订单 ID
    *   \]
  - `cursor` string

    分页游标
  - `has_more` boolean

    是否有更多记录

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "records": [
      {
        "id": "string",
        "refund_price": "string",
        "refund_shipping": "string",
        "refund_shipping_tax": "string",
        "refund_method": "string",
        "refund_status": "string",
        "note": "string",
        "created_at": "string",
        "updated_at": "string",
        "refund_line_items": [
          {
            "line_item_id": "string",
            "refund_quantity": 0,
            "tax": "string",
            "discount": "string",
            "sub_total": "string",
            "total": "string",
            "delete_quantity": 0
          }
        ],
        "payment_details": [
          {
            "id": "string",
            "payment_line_id": "string",
            "payment_channel": "string",
            "payment_method": "string",
            "refund_price": "string",
            "refund_status": "string",
            "finished_at": "string"
          }
        ],
        "additional_total": "string",
        "additional_prices": [
          {
            "name": "string",
            "price": "string",
            "biz_id": "string",
            "fee_title": "string"
          }
        ],
        "refund_tip": "string",
        "order_id": "string"
      }
    ],
    "cursor": "string",
    "has_more": true
  }
}
```