> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取退款单列表

> 退款单列表

退款单列表


## OpenAPI

````yaml openapi/v1-zh.yaml GET /api/v1/trades/{trade_id}/refunds
openapi: 3.0.3
info:
  title: Subotiz API
  description: Subotiz OpenAPI
  version: 1.0.0
servers:
  - url: https://{api}.subotiz.com
    variables:
      api:
        default: api
security:
  - sec0: []
tags:
  - name: 折扣
    description: 折扣
  - name: 发票
    description: 发票
  - name: 退款
    description: 退款
  - name: 商品管理
    description: 商品管理
  - name: 订阅
    description: 订阅
  - name: 商品定价
    description: 商品定价方案
  - name: 交易单
    description: 交易单
  - name: 支付流水
    description: 支付流水
  - name: 结账会话
    description: 结账会话
  - name: 顾客
    description: 顾客
  - name: 顾客门户
    description: 顾客门户
  - name: Webhook
    description: Webhook
  - name: 争议
    description: 争议订单
paths:
  /api/v1/trades/{trade_id}/refunds:
    get:
      tags:
        - 退款
      summary: 获取退款单列表
      description: 退款单列表
      operationId: v1-refund-list-refund
      parameters:
        - name: trade_id
          in: path
          description: 交易单ID
          required: true
          schema:
            type: string
        - name: refund_ids
          in: query
          description: 退款单ID数组，筛选退款单ID属于此数组的退款单
          schema:
            type: array
            items:
              type: string
        - name: refund_status
          in: query
          description: |-
            退款单状态数组，筛选退款单状态属于此数组的退款单
            - pending: 处理中
            - failed: 退款失败
            - succeeded: 退款成功
          schema:
            type: array
            items:
              type: string
        - name: starting_after
          in: query
          description: >-
            用于分页的游标。`starting_after` 是定义您在列表中位置的对象
            ID。例如，如果想获取下一页，可以在第一次获取对象列表之后，使用最后一个对象的 id 作为参数值。不能和 `ending_before
            同时使用
          schema:
            type: string
        - name: ending_before
          in: query
          description: >-
            用于分页的游标 `ending_before` 是定义您在列表中位置的对象
            ID。例如，如果想获取上一页，可以在第一次获取对象列表之后，使用第一个对象的 id 作为参数值。不能和 `starting_after`
            同时使用
          schema:
            type: string
        - name: limit
          in: query
          description: 分页参数，每页数量，默认：10，接口默认按创建时间倒序排序。限制：[1, 100]
          schema:
            type: integer
            format: int32
        - name: created_at.gt
          in: query
          description: 用于过滤的最小值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z')
          schema:
            type: string
        - name: created_at.gte
          in: query
          description: 用于过滤的最小值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z')
          schema:
            type: string
        - name: created_at.lt
          in: query
          description: 用于过滤的最大值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z')
          schema:
            type: string
        - name: created_at.lte
          in: query
          description: 用于过滤的最大值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z')
          schema:
            type: string
        - $ref: '#/components/parameters/HeaderRequestID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRefundResponse'
components:
  parameters:
    HeaderRequestID:
      name: Request-Id
      in: header
      description: 请求的唯一标识符
      required: true
      schema:
        type: string
        default: 008e3967-a1b5-48bb-be14-d5bff5092e61
  schemas:
    ListRefundResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/ListRefundResponse_Data'
    ListRefundResponse_Data:
      type: object
      properties:
        has_more:
          type: boolean
          description: 是否还有更多数据
        list:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: 退款单列表
    Refund:
      type: object
      properties:
        refund_id:
          type: string
          description: 退款单ID
        trade_id:
          type: string
          description: 交易单ID
        currency:
          type: string
          description: 金额对应的交易币种，编码遵照ISO4217
        callback_url:
          type: string
          description: Webhook通知回调地址
        reason:
          type: string
          description: 退款原因
        refund_amount:
          type: string
          description: 含税退款总额; refund_amount = item_refund_amount + tax_refund_amount
        refund_status:
          type: string
          description: |-
            退款状态
            - pending: 处理中
            - failed: 退款失败
            - succeeded: 退款成功
        metadata:
          type: object
          additionalProperties:
            type: string
          description: 元数据
        failure_reason:
          allOf:
            - $ref: '#/components/schemas/FailureReason'
          description: 退款失败原因
        ref_arn:
          type: string
          description: 发卡行侧返回退款凭证
        finished_at:
          type: string
          description: 退款完成时间
        item_refund_amount:
          type: string
          description: 商品侧退款金额(数字字符串)
        tax_refund_amount:
          type: string
          description: 税额侧退款金额(数字字符串); 非应税退款为 "0"
    FailureReason:
      type: object
      properties:
        code:
          type: string
          description: 系统返回交易返回码
        message:
          type: string
          description: 系统返回交易返回说明
  securitySchemes:
    sec0:
      type: http
      description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}'
      scheme: bearer

````