Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Reserve Plans Preview

ReservePlans are used to automatically place holds on a merchant’s funds until the plan expires. It takes a portion of each incoming Charge (including those resulting from a Transfer from a platform account).

Endpoints

The ReservePlan object Preview

Attributes

  • idstring

    Unique identifier for the object.

  • currencynullable enum

    Three-letter ISO currency code, in lowercase. Must be a supported currency. An unset currency indicates that the plan applies to all currencies.

  • fixed_releasenullable object

    Configuration specifying when all funds will be released when the plan is configured for fixed release.

  • metadatanullable object

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • percentinteger

    The percent of each Charge to reserve.

  • rolling_releasenullable object

    Configuration specifying how long reserves will be held when the plan is configured for rolling release.

  • statusenum

    The current status of the ReservePlan. The ReservePlan only affects charges if it is active.

    Possible enum values
    active

    The ReservePlan is active and reserving funds.

    disabled

    The ReservePlan has been manually disabled and is no longer reserving funds, and its associated funds have been released.

    disabling

    The ReservePlan is in the process of being disabled, and its associated funds are being released.

    expired

    The ReservePlan has expired automatically and is no longer reserving funds, and its associated funds have been released.

  • typeenum

    The type of the ReservePlan.

    Possible enum values
    fixed_release

    The ReservePlan releases funds after a fixed duration.

    rolling_release

    The ReservePlan releases funds on a rolling basis.

More attributes

  • objectstring

  • createdtimestamp

  • created_byenum

  • disabled_atnullable timestamp

  • livemodeboolean

The ReservePlan object
{
  "id": "resplan_61SxrVOzQu6XIJSCx41Q8rCFhzAUW",
  "object": "reserve.plan",
  "created": 1753380438,
  "created_by": "application",
  "currency": "usd",
  "disabled_at": null,
  "livemode": false,
  "metadata": {},
  "percent": 15,
  "rolling_release": {
    "days_after_charge": 30,
    "expires_on": 1755972438
  },
  "status": "active",
  "type": "rolling_release"
}

Create a ReservePlan Preview

Create a ReservePlan for a given account of a given type.

Parameters

  • percentintegerRequired

    The percentage of each Charge to reserve.

  • typeenumRequired

    The type of the ReservePlan.

    Possible enum values
    fixed_release

    The ReservePlan releases funds after a fixed duration.

    rolling_release

    The ReservePlan releases funds on a rolling basis.

  • currencyenum

    Three-letter ISO currency code, in lowercase. Must be a supported currency. Leave unset to create a ReservePlan for all currencies.

  • fixed_releaseobject

    Configuration specifying when all funds will be released when the ReservePlan is configured for fixed release.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • rolling_releaseobject

    Configuration specifying how long reserves will be held when the ReservePlan is configured for rolling release.

Returns

Returns a ReservePlan object.

POST /v1/reserve/plans
cURL
curl https://api.stripe.com/v1/reserve/plans \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d type=rolling_release \
  -d percent=15 \
  -d currency=usd \
  -d "rolling_release[days_after_charge]"=30 \
  -d "rolling_release[expires_on]"=1755972438
Response
{
  "id": "resplan_61SxrVOzQu6XIJSCx41Q8rCFhzAUW",
  "object": "reserve.plan",
  "created": 1753380438,
  "created_by": "application",
  "currency": "usd",
  "disabled_at": null,
  "livemode": false,
  "metadata": {},
  "percent": 15,
  "rolling_release": {
    "days_after_charge": 30,
    "expires_on": 1755972438
  },
  "status": "active",
  "type": "rolling_release"
}

Update a ReservePlan Preview

Update a ReservePlan’s configuration, percentage, or metadata.

Parameters

  • idstringRequired

    The identifier of the ReservePlan to update.

  • fixed_releaseobject

    Configuration specifying when all funds will be released when the ReservePlan is configured for fixed release.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • percentinteger

    The percentage of each Charge to reserve.

  • rolling_releaseobject

    Configuration specifying how long reserves will be held when the ReservePlan is configured for rolling release.

Returns

Returns the updated ReservePlan object.

POST /v1/reserve/plans/:id
cURL
curl https://api.stripe.com/v1/reserve/plans/resplan_61SxxwCbZ70gJfcoy41Q8rCFhzAUW \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d percent=20 \
  -d "rolling_release[days_after_charge]"=40 \
  -d "rolling_release[expires_on]"=1755997558 \
  -d "metadata[test_key]"=test_value
Response
{
  "id": "resplan_61SxxwCbZ70gJfcoy41Q8rCFhzAUW",
  "object": "reserve.plan",
  "created": 1753405164,
  "created_by": "application",
  "currency": "usd",
  "disabled_at": null,
  "livemode": false,
  "metadata": {
    "test_key": "test_value"
  },
  "percent": 20,
  "rolling_release": {
    "days_after_charge": 40,
    "expires_on": 1755997675
  },
  "status": "active",
  "type": "rolling_release"
}

Retrieve a ReservePlan Preview

Retrieve a ReservePlan.

Parameters

  • idstringRequired

    The identifier of the ReservePlan to retrieve.

Returns

Returns a ReservePlan object.

GET /v1/reserve/plans/:id
cURL
curl https://api.stripe.com/v1/reserve/plans/resplan_61SxrVOzQu6XIJSCx41Q8rCFhzAUW \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
Response
{
  "id": "resplan_61SxrVOzQu6XIJSCx41Q8rCFhzAUW",
  "object": "reserve.plan",
  "created": 1753380438,
  "created_by": "application",
  "currency": "usd",
  "disabled_at": null,
  "livemode": false,
  "metadata": {},
  "percent": 15,
  "rolling_release": {
    "days_after_charge": 30,
    "expires_on": 1755972438
  },
  "status": "active",
  "type": "rolling_release"
}