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

# List Refunds

> List all refunds with filtering and pagination

# List Refunds

Returns a paginated list of refunds for your business.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField query="transactionId" type="string">
  Filter by checkout session ID
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `pending`, `processing`, `completed`, `failed`
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page (1-100)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of refund objects

  <Expandable title="refund object">
    <ResponseField name="id" type="string">
      Unique refund identifier
    </ResponseField>

    <ResponseField name="checkoutSessionId" type="string">
      Associated session ID
    </ResponseField>

    <ResponseField name="amountInCents" type="integer">
      Refund amount in cents
    </ResponseField>

    <ResponseField name="reason" type="string">
      Refund reason
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Results per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of refunds
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # List all refunds
  curl "https://api.swiftpay.cx/api/refunds?page=1&limit=20" \
    -H "Authorization: Bearer mp_live_your_api_key"

  # Filter by session

  curl "https://api.swiftpay.cx/api/refunds?transactionId=sess_abc123" \
   -H "Authorization: Bearer mp_live_your_api_key"

  # Filter by status

  curl "https://api.swiftpay.cx/api/refunds?status=completed" \
   -H "Authorization: Bearer mp_live_your_api_key"

  ```

  ```javascript JavaScript theme={null}
  // List all refunds
  const response = await fetch(
    'https://api.swiftpay.cx/api/refunds?page=1&limit=20',
    {
      headers: {
        'Authorization': 'Bearer mp_live_your_api_key'
      }
    }
  );

  const refunds = await response.json();

  // Filter by specific session
  const sessionRefunds = await fetch(
    'https://api.swiftpay.cx/api/refunds?transactionId=sess_abc123',
    {
      headers: {
        'Authorization': 'Bearer mp_live_your_api_key'
      }
    }
  ).then(r => r.json());
  ```

  ```python Python theme={null}
  import requests

  # List all refunds
  response = requests.get(
      'https://api.swiftpay.cx/api/refunds',
      headers={'Authorization': 'Bearer mp_live_your_api_key'},
      params={'page': 1, 'limit': 20}
  )

  refunds = response.json()

  # Filter by status
  completed_refunds = requests.get(
      'https://api.swiftpay.cx/api/refunds',
      headers={'Authorization': 'Bearer mp_live_your_api_key'},
      params={'status': 'completed'}
  ).json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "ref_xyz789",
        "checkoutSessionId": "sess_abc123",
        "amountInCents": 2999,
        "reason": "Customer requested refund",
        "status": "completed",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "ref_abc456",
        "checkoutSessionId": "sess_def789",
        "amountInCents": 4999,
        "reason": "Product not as described",
        "status": "pending",
        "createdAt": "2024-01-14T15:20:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
  ```
</ResponseExample>