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

# List Refunds

> List all refunds with filtering and pagination options

<Note>
  This endpoint returns a paginated list of refunds. You can filter by status, date range, customer, and more.
</Note>

## Authentication

This endpoint requires a valid API key with `refunds:read` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer" default="10">
  Number of refunds to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of refunds to skip
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "pending", "approved", "processing", "completed", "rejected", "cancelled"
</ParamField>

<ParamField query="type" type="string">
  Filter by type: "full", "partial", "item\_return", "shipping", "tax\_only"
</ParamField>

<ParamField query="order_id" type="string">
  Filter by specific order
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer
</ParamField>

<ParamField query="created_after" type="string">
  Filter refunds created after date (ISO 8601)
</ParamField>

<ParamField query="created_before" type="string">
  Filter refunds created before date (ISO 8601)
</ParamField>

<ParamField query="reason" type="string">
  Filter by refund reason code
</ParamField>

<ParamField query="sort_by" type="string" default="created_at">
  Sort by field: "created\_at", "updated\_at", "amount", "status"
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort order: "asc" or "desc"
</ParamField>

### Response

Returns a paginated list of refund objects.

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/refunds?status=processing&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const refunds = await stateset.refunds.list({
    status: 'processing',
    limit: 20
  });
  ```

  ```python Python theme={null}
  refunds = stateset.refunds.list(
    status='processing',
    limit=20
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
        "object": "refund",
        "order_id": "order_123456",
        "customer_id": "cust_abc123",
        "type": "partial",
        "status": "processing",
        "reason": "product_damaged",
        "amounts": {
          "total": 5449,
          "currency": "USD"
        },
        "created_at": "2024-06-20T13:30:00Z",
        "estimated_completion": "2024-06-23T13:30:00Z"
      },
      {
        "id": "refund_1234f083-bb2d-54d6-bg6d-1b0e3gd75f41",
        "object": "refund",
        "order_id": "order_234567",
        "customer_id": "cust_def456",
        "type": "full",
        "status": "processing",
        "reason": "order_cancelled",
        "amounts": {
          "total": 15999,
          "currency": "USD"
        },
        "created_at": "2024-06-20T12:00:00Z",
        "estimated_completion": "2024-06-23T12:00:00Z"
      }
    ],
    "has_more": true,
    "total_count": 156,
    "url": "/v1/refunds",
    "summary": {
      "total_amount": 847532,
      "average_processing_time": 72,
      "status_breakdown": {
        "pending": 12,
        "approved": 8,
        "processing": 45,
        "completed": 87,
        "rejected": 3,
        "cancelled": 1
      }
    }
  }
  ```
</ResponseExample>