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 Holds Preview

ReserveHolds are used to place a temporary ReserveHold on a merchant’s funds.

Endpoints

The ReserveHold object Preview

Attributes

  • idstring

    Unique identifier for the object.

  • amountinteger

    Amount reserved. A positive integer representing how much is reserved in the smallest currency unit.

  • currencyenum

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • metadatanullable objectConnect Only

    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.

  • release_scheduleobject

    Information about the release schedule of the ReserveHold.

More attributes

  • objectstring

  • amount_releasablenullable integerConnect Only

  • createdtimestamp

  • created_byenum

  • is_releasablenullable booleanConnect Only

  • livemodeboolean

  • reasonenum

  • reserve_plannullable stringExpandable

  • source_chargenullable stringExpandable

  • source_typeenum

The ReserveHold object
{
  "id": "reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW",
  "object": "reserve.hold",
  "amount": 1000,
  "amount_releasable": 1000,
  "created": 1753380387,
  "created_by": "application",
  "currency": "usd",
  "is_releasable": true,
  "livemode": false,
  "metadata": {},
  "reason": "standalone",
  "release_schedule": {
    "release_after": 1755972386,
    "scheduled_release": 1755993600
  },
  "reserve_plan": null,
  "source_charge": null,
  "source_type": "card"
}

Create a ReserveHold Preview

Create a ReserveHold.

Parameters

  • amountintegerRequired

    Amount to reserve. A positive integer representing how much to reserve in the smallest currency unit (e.g., 100 cents to reserve $1.00 or 100 to reserve ¥100, a zero-decimal currency).

  • currencyenumRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • release_scheduleobjectRequired

    Configure when the ReserveHold will be released.

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

More parameters

  • source_typestring

Returns

Returns a ReserveHold object.

POST /v1/reserve/holds
cURL
curl https://api.stripe.com/v1/reserve/holds \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d amount=1000 \
  -d currency=usd \
  -d "release_schedule[release_after]"=1755972386
Response
{
  "id": "reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW",
  "object": "reserve.hold",
  "amount": 1000,
  "amount_releasable": 1000,
  "created": 1753380387,
  "created_by": "application",
  "currency": "usd",
  "is_releasable": true,
  "livemode": false,
  "metadata": {},
  "reason": "standalone",
  "release_schedule": {
    "release_after": 1755972386,
    "scheduled_release": 1755993600
  },
  "reserve_plan": null,
  "source_charge": null,
  "source_type": "card"
}

Update a ReserveHold Preview

Update a ReserveHold’s release schedule or metadata.

Parameters

  • idstringRequired

    The identifier of the ReserveHold to update.

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

  • release_scheduleobject

    Configure when the ReserveHold will be released.

Returns

Returns the updated ReserveHold object.

POST /v1/reserve/holds/:id
cURL
curl https://api.stripe.com/v1/reserve/holds/reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d "release_schedule[release_after]"=1758588150 \
  -d "metadata[test_key]"=test_value
Response
{
  "id": "reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW",
  "object": "reserve.hold",
  "amount": 1000,
  "amount_releasable": 1000,
  "created": 1753380387,
  "created_by": "application",
  "currency": "usd",
  "is_releasable": true,
  "livemode": false,
  "metadata": {
    "test_key": "test_value"
  },
  "reason": "standalone",
  "release_schedule": {
    "release_after": 1758588150,
    "scheduled_release": 1758672000
  },
  "reserve_plan": null,
  "source_charge": null,
  "source_type": "card"
}

Retrieve a ReserveHold Preview

Retrieve a ReserveHold.

Parameters

  • idstringRequired

    The identifier of the ReserveHold to retrieve.

Returns

Returns a ReserveHold object.

GET /v1/reserve/holds/:id
cURL
curl https://api.stripe.com/v1/reserve/holds/reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
Response
{
  "id": "reshold_61SxrUZH1aQJj97WT41Q8rCFhzAUW",
  "object": "reserve.hold",
  "amount": 1000,
  "amount_releasable": 1000,
  "created": 1753380387,
  "created_by": "application",
  "currency": "usd",
  "is_releasable": true,
  "livemode": false,
  "metadata": {},
  "reason": "standalone",
  "release_schedule": {
    "release_after": 1755972386,
    "scheduled_release": 1755993600
  },
  "reserve_plan": null,
  "source_charge": null,
  "source_type": "card"
}