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

Balance Settings

Options for customizing account balances and payout settings for a Stripe platform’s connected accounts.

Endpoints

The Balance Setting object

Attributes

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • paymentsobject

    Settings that apply to the Payments Balance.

The Balance Setting object
{
  "object": "balance_settings",
  "payments": {
    "debit_negative_balances": true,
    "payouts": {
      "schedule": {
        "interval": "daily"
      },
      "statement_descriptor": null,
      "status": "enabled"
    },
    "settlement_timing": {
      "delay_days": 2
    }
  }
}

Update balance settings

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

Parameters

Returns

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

POST /v1/balance_settings
cURL
curl https://api.stripe.com/v1/balance_settings \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -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": {
      "schedule": {
        "interval": "monthly",
        "monthly_payout_days": [
          5,
          20
        ]
      },
      "statement_descriptor": null,
      "status": "enabled"
    },
    "settlement_timing": {
      "delay_days": 2
    }
  }
}

Retrieve balance settings

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

Parameters

No parameters.

Returns

Returns a balance settings object for the account specified in the request.

GET /v1/balance_settings
curl https://api.stripe.com/v1/balance_settings \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"
Response
{
  "object": "balance_settings",
  "payments": {
    "debit_negative_balances": true,
    "payouts": {
      "schedule": {
        "interval": "daily"
      },
      "statement_descriptor": null,
      "status": "enabled"
    },
    "settlement_timing": {
      "delay_days": 2
    }
  }
}