Stripe: Retrieve balance settings

Stripe balanceSettings.getBalanceSettings: arguments, response, policy and SDK examples.

← Balance settings operations · Get started

Operation stripe.getbalancesettings

Provider route: GET /v1/balance_settings. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["balanceSettings"]["getBalanceSettings"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.balanceSettings.getBalanceSettings(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.balance_settings.get_balance_settings(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`query`	object	Optional	Additional keys: not allowed
`query.expand`	array	Optional
`query.expand[]`	string	Each item	Maximum length: 5000

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
`$`	Model	Root	Expand Update balance settings — response body

Referenced models: Update balance settings — response body

Schemas

1 more schema is linked from the tables above, on the schema pages.

Update balance settings — response body

Field	Type	Presence	Description and constraints
`$`	object	Root	Options for customizing account balances and payout settings for a Stripe platform’s connected accounts.
`object`	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: balance_settings
`payments`	Model	Required within parent	Expand Update balance settings — response body — payments

Referenced models: Update balance settings — response body — payments

Update balance settings — response body — payments

Field	Type	Presence	Description and constraints
`$`	object	Root
`debit_negative_balances`	JSON	Optional
`debit_negative_balances (anyOf 1)`	boolean	Alternative	A Boolean indicating if Stripe should try to reclaim negative balances from an attached bank account. See [Understanding Connect account balances](/connect/account-balances) for details. The default value is `false` when [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, otherwise `true`.
`debit_negative_balances (anyOf 2)`	null	Alternative
`payouts`	JSON	Optional
`payouts (anyOf 1)`	JSON	Alternative	Settings specific to the account's payouts.
`payouts (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled
`payouts (anyOf 2)`	null	Alternative
`settlement_timing`	Model	Required within parent	Expand Update balance settings — response body — payments settlement timing

Referenced models: Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled, Update balance settings — response body — payments settlement timing

Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled

Field	Type	Presence	Description and constraints
`$`	object	Root
`automatic_transfer_rules_by_currency`	JSON	Optional
`automatic_transfer_rules_by_currency (anyOf 1)`	object	Alternative	Configures per-currency rules for automatically transferring funds from the payments balance to a FinancialAccount. Additional keys: see wildcard field
`automatic_transfer_rules_by_currency (anyOf 1).*`	array	Additional keys
`automatic_transfer_rules_by_currency (anyOf 1).*[]`	Model	Each item	Expand Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled automatic transfer rules by currency object value item
`automatic_transfer_rules_by_currency (anyOf 2)`	null	Alternative
`minimum_balance_by_currency`	JSON	Optional
`minimum_balance_by_currency (anyOf 1)`	object	Alternative	The minimum balance amount to retain per currency after automatic payouts. Only funds that exceed these amounts are paid out. Learn more about the [minimum balances for automatic payouts](/payouts/minimum-balances-for-automatic-payouts). Additional keys: see wildcard field
`minimum_balance_by_currency (anyOf 1).*`	JSON	Additional keys
`minimum_balance_by_currency (anyOf 1).* (anyOf 1)`	integer	Alternative
`minimum_balance_by_currency (anyOf 1).* (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`minimum_balance_by_currency (anyOf 2)`	null	Alternative
`schedule`	JSON	Optional
`schedule (anyOf 1)`	JSON	Alternative	Details on when funds from charges are available, and when they are paid out to an external account. See our [Setting Bank and Debit Card Payouts](https://docs.stripe.com/connect/bank-transfers#payout-information) documentation for details.
`schedule (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled schedule value interval, monthly payout days, weekly payout days
`schedule (anyOf 2)`	null	Alternative
`statement_descriptor`	JSON	Optional
`statement_descriptor (anyOf 1)`	string	Alternative	The text that appears on the bank account statement for payouts. If not set, this defaults to the platform's bank descriptor as set in the Dashboard. Maximum length: 5000
`statement_descriptor (anyOf 2)`	null	Alternative
`status`	string	Required within parent	Whether the funds in this account can be paid out. Known values: disabled, enabled

Referenced models: Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled automatic transfer rules by currency object value item, Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled schedule value interval, monthly payout days, weekly payout days

Update balance settings — response body — payments settlement timing

Field	Type	Presence	Description and constraints
`$`	object	Root
`delay_days`	JSON	Required within parent
`delay_days (anyOf 1)`	integer	Alternative	The number of days charge funds are held before becoming available.
`delay_days (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`delay_days_override`	JSON	Optional
`delay_days_override (anyOf 1)`	integer	Alternative	The number of days charge funds are held before becoming available. If present, overrides the default, or minimum available, for the account.
`delay_days_override (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`start_of_day`	JSON	Optional
`start_of_day (anyOf 1)`	JSON	Alternative	Customized start of day configuration for automatic payouts to group and send payments in local timezones with a customized day starting time. For details, see our [Customized start of day](/connect/customized-start-of-day) documentation.
`start_of_day (anyOf 1) (anyOf 1)`	Model	Alternative	Expand Update balance settings — response body — payments settlement timing start of day value hour, minutes, timezone
`start_of_day (anyOf 2)`	null	Alternative

Referenced models: Update balance settings — response body — payments settlement timing start of day value hour, minutes, timezone

Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled automatic transfer rules by currency object value item

Field	Type	Presence	Description and constraints
`$`	object	Root
`payout_method`	string	Required within parent	The ID of the FinancialAccount that funds will be transferred to during automatic transfers. Maximum length: 5000
`transfer_up_to_amount`	JSON	Optional
`transfer_up_to_amount (anyOf 1)`	JSON	Alternative
`transfer_up_to_amount (anyOf 1) (anyOf 1)`	integer	Alternative	The maximum amount in minor units to transfer to the FinancialAccount. Only applicable when `type` is `transfer_up_to_amount`.
`transfer_up_to_amount (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`transfer_up_to_amount (anyOf 2)`	null	Alternative
`type`	string	Required within parent	The type of automatic transfer rule. Known values: transfer_all, transfer_up_to_amount

Update balance settings — response body — payments / payouts / Settings specific to the account's payouts / status: disabled, enabled schedule value interval, monthly payout days, weekly payout days

Field	Type	Presence	Description and constraints
`$`	object	Root
`interval`	JSON	Optional
`interval (anyOf 1)`	string	Alternative	How frequently funds will be paid out. One of `manual` (payouts only created via API call), `daily`, `weekly`, or `monthly`. Known values: daily, manual, monthly, weekly
`interval (anyOf 2)`	null	Alternative
`monthly_payout_days`	array	Optional	The day of the month funds will be paid out. Only shown if `interval` is monthly. Payouts scheduled between the 29th and 31st of the month are sent on the last day of shorter months.
`monthly_payout_days[]`	JSON	Each item
`monthly_payout_days[] (anyOf 1)`	integer	Alternative
`monthly_payout_days[] (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`weekly_payout_days`	array	Optional	The days of the week when available funds are paid out, specified as an array, for example, [`monday`, `tuesday`]. Only shown if `interval` is weekly.
`weekly_payout_days[]`	string	Each item	Known values: friday, monday, thursday, tuesday, wednesday

Policy, approvals and errors

SDK function policy ID: stripe.getbalancesettings. Catalog operation: GetBalanceSettings. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source

Report an issue with this page