# Settlement reserves

Review settlement reserve activity.

Settlement reserves help manage risk by temporarily holding pending and incoming payment funds while preserving access to funds that have already settled.

A settlement reserve moves existing pending payment funds and incoming payment proceeds into a separate balance. Already available funds remain usable, subject to other account restrictions. Released funds return to the payments balance and retain their original availability date.

For example, consider an account with 500 USD available and 200 USD pending at the start of a settlement reserve. The 200 USD and incoming payment proceeds become reserved, while the existing 500 USD remains usable.

## Retrieve settlement reserves

Use the Reserves API to identify active settlement plans and inspect their holds and releases.

If you use a restricted API key, grant it `reserve_plan_read`, `reserve_hold_read`, `reserve_release_read`, `balance_amount_read`, and `balance_read` permissions for the requests on this page.

### Identify the reserve

[List reserve plans](https://docs.stripe.com/api/reserve/plan/list.md?api-version=2026-09-30.preview) with `status=active` and `destination=settlement_reserved`.

```curl
curl -G https://api.stripe.com/v1/reserve/plans \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d status=active \
  -d destination=settlement_reserved
```

```json
{
  "data": [
    {
      "id": "resplan_61SToUQzaDa1N5nJh412e824LPfdz",
      "object": "reserve.plan",
      "created_by": "stripe",
      "destination": "settlement_reserved",
      "manual_release": {},
      "percent": 100,
      "status": "active",
      "type": "manual_release"
    }
  ],
  "has_more": false
}
```

### Review reserved amounts

[Retrieve your balance](https://docs.stripe.com/api/balance/balance_retrieve.md?api-version=2026-09-30.preview) to compare your payments and settlement reserve balances.

```curl
curl https://api.stripe.com/v1/balance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview"
```

```json
{
  "object": "balance",
  "available": [
    {
      "amount": 50000,
      "currency": "usd"
    }
  ],
  "pending": [
    {
      "amount": 0,
      "currency": "usd"
    }
  ],
  "settlement_reserved": {
    "available": [
      {
        "amount": 0,
        "currency": "usd"
      }
    ],
    "pending": [
      {
        "amount": 20000,
        "currency": "usd"
      }
    ]
  }
}
```

The API expresses amounts in the [smallest currency unit](https://docs.stripe.com/currencies.md#zero-decimal), so `50000` represents 500 USD and `20000` represents 200 USD. Funds in `settlement_reserved.available` successfully settled, but remain reserved and aren’t available for payouts or other outbound money movement.

Don’t infer whether a plan is active from the balance response. A nonzero reserved balance can remain while releases are processing. Use the Reserves API to determine a plan’s status.

### Inspect held funds

[List reserve holds](https://docs.stripe.com/api/reserve/hold/list.md?api-version=2026-09-30.preview) for the plan to identify reserved payment proceeds.

```curl
curl -G https://api.stripe.com/v1/reserve/holds \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d reserve_plan={{RESERVE_PLAN_ID}}
```

```json
{
  "data": [
    {
      "id": "reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW",
      "object": "reserve.hold",
      "amount": 20000,
      "currency": "usd",
      "destination": "settlement_reserved",
      "release_schedule": {
        "release_after": null,
        "scheduled_release": null
      },
      "reserve_plan": "resplan_61SToUQzaDa1N5nJh412e824LPfdz",
      "source_charge": "ch_3Qexample123456789"
    }
  ],
  "has_more": false
}
```

Each hold represents reserved proceeds from a payment. Use `source_charge` to relate the hold to the original charge without counting the held amount as another payment.

### Monitor releases

[List reserve releases](https://docs.stripe.com/api/reserve/release/list.md?api-version=2026-09-30.preview) by plan to retrieve its releases. The following response shows a release with the `plan_disabled` reason.

```curl
curl -G https://api.stripe.com/v1/reserve/releases \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d reserve_plan={{RESERVE_PLAN_ID}}
```

```json
{
  "data": [
    {
      "id": "resrel_61SxyHbQOe90T6sLB41Q8rCFhzAUW",
      "object": "reserve.release",
      "amount": 20000,
      "currency": "usd",
      "destination": "payments",
      "reason": "plan_disabled",
      "reserve_hold": null,
      "reserve_plan": "resplan_61SToUQzaDa1N5nJh412e824LPfdz"
    }
  ],
  "has_more": false
}
```

To confirm that all held funds return to your payments balance, reconcile `plan_disabled` releases at the plan level because they can include funds from multiple holds. Release processing is asynchronous, so a disabled plan doesn’t mean every held amount has returned. New holds don’t occur after a plan is disabled.

To associate release amounts with individual holds, retrieve the plan’s holds, include each hold’s `release_details`, and match their `reserve_release` values to the release ID. You can also filter releases by a specific `reserve_hold` ID to return only releases associated with that hold, including reversals resulting from refunds or disputes.

## Reconcile balance transactions

To reconcile reserve movements in your reporting, use the paired [balance transactions](https://docs.stripe.com/api/balance_transactions.md?api-version=2026-09-30.preview) for each hold and release. These transactions explain changes to your payments and settlement reserve balances. Keep reserve movements separate from the original payment transaction to avoid counting the payment proceeds twice.

| Movement | Transaction type | Public balance type | Direction |
| --- | --- | --- | --- |
| Hold: payments side | `reserved_funds` | `payments` | Debit |
| Hold: reserve side | `reserve_hold` | `settlement_reserved` | Credit |
| Release: reserve side | `reserve_release` | `settlement_reserved` | Debit |
| Release: payments side | `reserved_funds` | `payments` | Credit |

[List balance transactions](https://docs.stripe.com/api/balance_transactions/list.md?api-version=2026-09-30.preview) with a supported `type` or `source` filter, then inspect each result’s `balance_type`. You can’t pass `balance_type` as a filter parameter in the request.

Retrieve the two sides of a release by filtering for its `resrel_` source. This example shows the 200 USD returning after its original settlement date:

```curl
curl -G https://api.stripe.com/v1/balance_transactions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.preview" \
  -d source=resrel_61SxyHbQOe90T6sLB41Q8rCFhzAUW
```

```json
{
  "data": [
    {
      "id": "txn_release_reserve_example",
      "amount": -20000,
      "balance_type": "settlement_reserved",
      "currency": "usd",
      "net": -20000,
      "source": "resrel_61SxyHbQOe90T6sLB41Q8rCFhzAUW",
      "status": "available",
      "type": "reserve_release"
    },
    {
      "id": "txn_release_payments_example",
      "amount": 20000,
      "balance_type": "payments",
      "currency": "usd",
      "net": 20000,
      "reporting_category": "settlement_reserved_funds",
      "source": "resrel_61SxyHbQOe90T6sLB41Q8rCFhzAUW",
      "status": "available",
      "type": "reserved_funds"
    }
  ]
}
```

Hold-side transactions share a `reshold_` source. Retrieve the corresponding reserve hold to find its original charge and plan. Release-side transactions share a `resrel_` source. Retrieve the corresponding reserve release to find its plan or associated hold.

When reconciling, consider both `balance_type` and `status` because:

- A reserve-side transaction with `status: "available"` still represents reserved funds.
- Funds released before their original settlement date return to the payments balance as pending until that date.
- Funds released after settlement return as available.
- Plan disabling and balance availability are separate states.
- Refunds and disputes can release funds by a hold reversal, but release processing can be asynchronous.

If a risk reserve and settlement reserve both apply to a payment, the risk reserve’s share is reserved first and the remainder goes into the settlement reserve. Reconcile each hold independently.

## Listen for reserve events

Subscribe an [event destination](https://docs.stripe.com/webhooks.md) to reserve events and configure it with API version `2026-09-30.preview` or later. The API version on a REST request doesn’t change the event destination’s version. Reserve activity can produce multiple holds for one payment when both risk and settlement reserves apply. Plan for event volume to track payment volume.

Before handling reserve events, [verify incoming webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) and allow traffic from Stripe [public IP addresses](https://docs.stripe.com/ips.md).

| Event | Integration action |
| --- | --- |
| `reserve.plan.created` | Check `destination`, then refresh active reserve state for settlement plans. |
| `reserve.hold.created` | Check `destination`, record the hold, and refresh reconciliation data. |
| `reserve.plan.disabled` | Mark the plan inactive. Don’t assume all held funds have returned. |
| `reserve.release.created` | Reconcile the completed release and refresh the balance. Follow its plan for a bulk plan-disable release, or its hold for a charge-linked release, because its destination is `payments`. |
| `balance.available` | Refresh available amounts. Don’t treat this as an event for every reserve movement. |
| `account.updated` | Refresh account requirements independently of reserve state. Don’t use `payouts_enabled` as a settlement reserve indicator. |