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

Update balance settings 

Connect
Balance Settings
Update balance settings

Updates balance settings for a given connected account. Related guide: Making API calls for connected accounts

Parameters

  • paymentsobject

    Settings that apply to the Payments Balance.

    • payments.debit_negative_balancesboolean

      A Boolean indicating whether Stripe should try to reclaim negative balances from an attached bank account. For details, see Understanding Connect Account Balances.

    • payments.payoutsobject

      Settings specific to the account’s payouts.

      • payments.payouts.minimum_balance_by_currencyobject

        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.

      • payments.payouts.scheduleobject

        Details on when funds from charges are available, and when they are paid out to an external account. For details, see our Setting Bank and Debit Card Payouts documentation.

        • payments.payouts.schedule.intervalenum

          How frequently available funds are paid out. One of: daily, manual, weekly, or monthly. Default is daily.

          Possible enum values
          daily

          Stripe automatically sends money to your bank account daily

          manual

          You manually send funds to your bank account

          monthly

          Stripe automatically sends money to your bank account monthly

          weekly

          Stripe automatically sends money to your bank account weekly

        • payments.payouts.schedule.monthly_payout_daysarray of integers

          The days of the month when available funds are paid out, specified as an array of numbers between 1–31. Payouts nominally scheduled between the 29th and 31st of the month are instead sent on the last day of a shorter month. Required and applicable only if interval is monthly.

        • payments.payouts.schedule.weekly_payout_daysarray of enums

          The days of the week when available funds are paid out, specified as an array, e.g., [monday, tuesday]. Required and applicable only if interval is weekly.

          Possible enum values
          friday

          Select Friday as one of the weekly payout day

          monday

          Select Monday as one of the weekly payout day

          thursday

          Select Thursday as one of the weekly payout day

          tuesday

          Select Tuesday as one of the weekly payout day

          wednesday

          Select Wednesday as one of the weekly payout day

      • payments.payouts.statement_descriptorstring

        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.

    • payments.settlement_timingobject

      Settings related to the account’s balance settlement timing.

      • payments.settlement_timing.delay_days_overrideinteger

        Change delay_days for this account, which determines the number of days charge funds are held before becoming available. The maximum value is 31. Passing an empty string to delay_days_override will return delay_days to the default, which is the lowest available value for the account. Learn more about controlling delay days.

Returns

Returns the updated balance settings object for the account that was authenticated in the request.

POST /v1/balance_settings
curl https://api.stripe.com/v1/balance_settings \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d "payments[payouts][schedule][interval]"=monthly \
  -d "payments[payouts][schedule][monthly_payout_days][]"=5 \
  -d "payments[payouts][schedule][monthly_payout_days][]"=20
Response
{
  "object": "balance_settings",
  "payments": {
    "debit_negative_balances": true,
    "payouts": {
      "minimum_balance_by_currency": {
        "usd": 1500,
        "cad": 8000
      },
      "schedule": {
        "interval": "monthly",
        "monthly_payout_days": [
          5,
          20
        ]
      },
      "statement_descriptor": null,
      "status": "enabled"
    },
    "settlement_timing": {
      "delay_days_override": 3,
      "delay_days": 3
    }
  }
}