- Breaking changes
- Public preview
Nests the Balance Settings request object under a new Payments parameter Breaking changes Public preview
What’s new
Moves the Balance Settings request object and response to a new, required top-level payments parameter. This change makes it clear that the settings apply only to the Payments Balance.
Why is this a breaking change?
A new, required top-level payments parameter has been added to the Balance Settings request object and response. This parameter is now the parent of all existing parameters in the Balance Settings object.
Impact
If you participate in the Accounts v2 API public preview and want to use API version 2025-08-27.preview or later, you need to update your integration to use the new, top-level parameter.
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| payments | Added | BalanceSettings BalanceSettings#update |
| debit_negative_balances payouts settlement_timing | Removed | BalanceSettings BalanceSettings#update |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2025-08-27. preview
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
Learn more about Stripe API upgrades.