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

Cash Balance 

A customer’s Cash balance represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.

Endpoints

The Cash balance object 

Attributes

  • objectstring

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

  • availablenullable object

    A hash of all cash balances available to this customer. You cannot delete a customer with any cash balances, even if the balance is 0. Amounts are represented in the smallest currency unit.

  • customerstring

    The ID of the customer whose cash balance this object represents.

  • customer_accountnullable stringPreview feature

    The ID of the account whose cash balance this object represents.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • settingsobject

    A hash of settings for this cash balance.

The Cash balance object
{
  "object": "cash_balance",
  "available": {
    "eur": 10000
  },
  "customer": "cus_OaCLf8Fi1nbFpJ",
  "livemode": false,
  "settings": {
    "reconciliation_mode": "automatic",
    "using_merchant_default": true
  }
}

Update a cash balance's settings 

Changes the settings on a customer’s cash balance.

Parameters

  • settingsobject

    A hash of settings for this cash balance.

Returns

The customer’s cash balance, with the updated settings.

POST /v1/customers/:id/cash_balance
curl https://api.stripe.com/v1/customers/cus_Ob4Xiw8KXOqcvM/cash_balance \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-06-30.basil" \
  -d "settings[reconciliation_mode]"=manual
Response
{
  "object": "cash_balance",
  "available": null,
  "customer": "cus_Ob4Xiw8KXOqcvM",
  "livemode": false,
  "settings": {
    "reconciliation_mode": "manual",
    "using_merchant_default": false
  }
}

Retrieve a cash balance 

Retrieves a customer’s cash balance.

Parameters

No parameters.

Returns

The Cash Balance object for a given customer.

GET /v1/customers/:id/cash_balance
curl https://api.stripe.com/v1/customers/cus_OaCLf8Fi1nbFpJ/cash_balance \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-06-30.basil"
Response
{
  "object": "cash_balance",
  "available": {
    "eur": 10000
  },
  "customer": "cus_OaCLf8Fi1nbFpJ",
  "livemode": false,
  "settings": {
    "reconciliation_mode": "automatic",
    "using_merchant_default": true
  }
}