> ## 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 Reserves

> List all reserve records with filtering and pagination

# List Reserves

Returns a paginated list of individual reserve records for your business.

## Request

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

<ParamField query="status" type="string">
  Filter by status: `active`, `partially_released`, `released`, `consumed`
</ParamField>

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

<ParamField query="cursor" type="string">
  Pagination cursor for next page
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      Array of reserve objects

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

        <ResponseField name="paymentId" type="string">
          Associated payment ID
        </ResponseField>

        <ResponseField name="originalAmountInCents" type="integer">
          Original transaction amount in cents
        </ResponseField>

        <ResponseField name="reserveAmountInCents" type="integer">
          Amount held in reserve in cents
        </ResponseField>

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

        <ResponseField name="releaseAt" type="string">
          Scheduled release date (ISO 8601)
        </ResponseField>

        <ResponseField name="reservedAt" type="string">
          Creation timestamp (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nextCursor" type="string">
      Cursor for the next page of results
    </ResponseField>
  </Expandable>
</ResponseField>

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

  # Filter by status

  curl "https://api.swiftpay.cx/api/reserves?status=active&limit=50" \
   -H "Authorization: Bearer mp_live_your_api_key"

  # Paginate

  curl "https://api.swiftpay.cx/api/reserves?cursor=cursor_abc123" \
   -H "Authorization: Bearer mp_live_your_api_key"

  ```

  ```javascript JavaScript theme={null}
  // List active reserves
  const response = await fetch(
    'https://api.swiftpay.cx/api/reserves?status=active&limit=50',
    {
      headers: {
        'Authorization': 'Bearer mp_live_your_api_key'
      }
    }
  );

  const reserves = await response.json();

  // Display upcoming releases
  reserves.data.items.forEach(reserve => {
    const releaseAt = new Date(reserve.releaseAt);
    const amount = (reserve.reserveAmountInCents / 100).toFixed(2);
    console.log(`$${amount} releasing on ${releaseAt.toLocaleDateString()}`);
  });
  ```

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

  # List active reserves
  response = requests.get(
      'https://api.swiftpay.cx/api/reserves',
      headers={'Authorization': 'Bearer mp_live_your_api_key'},
      params={'status': 'active', 'limit': 50}
  )

  reserves = response.json()

  for reserve in reserves['data']['items']:
      amount = reserve['reserveAmountInCents'] / 100
      print(f"${amount:.2f} - Status: {reserve['status']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "items": [
        {
          "id": "res_abc123",
          "paymentId": "sess_xyz789",
          "originalAmountInCents": 10000,
          "reserveAmountInCents": 10000,
          "reservePercentage": 10,
          "status": "active",
          "releasedAmountInCents": 0,
          "releaseAt": "2024-02-15T00:00:00Z",
          "releasedAt": null,
          "reservedAt": "2024-01-15T10:30:00Z"
        },
        {
          "id": "res_def456",
          "paymentId": "sess_uvw123",
          "originalAmountInCents": 5000,
          "reserveAmountInCents": 3000,
          "reservePercentage": 10,
          "status": "partially_released",
          "releasedAmountInCents": 2000,
          "releaseAt": "2024-02-10T00:00:00Z",
          "releasedAt": null,
          "reservedAt": "2024-01-10T14:20:00Z"
        }
      ],
      "nextCursor": "cursor_xyz789"
    }
  }
  ```
</ResponseExample>

## Reserve Statuses

| Status               | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `active`             | Reserve is locked, awaiting release date              |
| `partially_released` | Some funds consumed by refund, remainder still locked |
| `released`           | Full amount released to available balance             |
| `consumed`           | Entire reserve used for refund/chargeback             |

<Tip>
  For a detailed explanation of the reserve lifecycle and how they affect your
  balance, see the [Understanding Reserves
  guide](/guides/understanding-reserves).
</Tip>