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

# Get Reserve

> Retrieve a specific reserve record by ID

# Get Reserve

Retrieves the details of a specific reserve record.

## Request

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

<ParamField path="id" type="string" required>
  The unique identifier of the reserve (e.g., `res_abc123`)
</ParamField>

## Response

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

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

    <ResponseField name="paymentId" type="string">
      Associated payment or checkout session 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="reservePercentage" type="integer">
      Percentage of the transaction held in reserve
    </ResponseField>

    <ResponseField name="status" type="string">
      Reserve status: `active`, `partially_released`, `released`, `consumed`
    </ResponseField>

    <ResponseField name="releasedAmountInCents" type="integer">
      Amount already released from this reserve
    </ResponseField>

    <ResponseField name="releaseAt" type="string">
      Scheduled release date (ISO 8601). `null` for indefinite holds.
    </ResponseField>

    <ResponseField name="releasedAt" type="string">
      Actual release timestamp (ISO 8601). `null` if not yet released.
    </ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.swiftpay.cx/api/reserves/res_abc123 \
    -H "Authorization: Bearer mp_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const reserveId = "res_abc123";

  const response = await fetch(
     `https://api.swiftpay.cx/api/reserves/${reserveId}`,
     {
        headers: {
           Authorization: "Bearer mp_live_your_api_key",
        },
     }
  );

  const reserve = await response.json();

  // Check if partially released
  if (reserve.data.releasedAmountInCents > 0) {
     console.log(
        `$${(reserve.data.releasedAmountInCents / 100).toFixed(
           2
        )} already released`
     );
  }
  ```

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

  reserve_id = 'res_abc123'

  response = requests.get(
      f'https://api.swiftpay.cx/api/reserves/{reserve_id}',
      headers={'Authorization': 'Bearer mp_live_your_api_key'}
  )

  reserve = response.json()
  data = reserve['data']

  if data['reserveAmountInCents'] < data['originalAmountInCents']:
      consumed = data['originalAmountInCents'] - data['reserveAmountInCents']
      print(f"${consumed / 100:.2f} consumed for refunds")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "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"
    }
  }
  ```

  ```json 200 (Partially Released) theme={null}
  {
     "success": true,
     "data": {
        "id": "res_def456",
        "paymentId": "sess_uvw123",
        "originalAmountInCents": 10000,
        "reserveAmountInCents": 3000,
        "reservePercentage": 10,
        "status": "partially_released",
        "releasedAmountInCents": 7000,
        "releaseAt": "2024-02-10T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-10T14:20:00Z"
     }
  }
  ```

  ```json 404 theme={null}
  {
     "success": false,
     "error": {
        "type": "not_found",
        "message": "Reserve not found",
        "requestId": "req_abc123"
     }
  }
  ```
</ResponseExample>

## Amount Tracking

Reserves track both original and current amounts:

| Field                   | Description                         |
| ----------------------- | ----------------------------------- |
| `originalAmountInCents` | Amount when reserve was created     |
| `reserveAmountInCents`  | Remaining amount currently held     |
| `releasedAmountInCents` | Amount already released or consumed |

When a refund consumes reserve funds:

* `reserveAmountInCents` decreases
* `releasedAmountInCents` increases
* Status changes to `partially_released` or `released`

<Note>
  If `reserveAmountInCents` equals 0, the entire reserve was released or
  consumed.
</Note>