Stripe: Balance schemas
13 Stripe schemas with complete fields and constraints.
← Balance operations · All schemas
List all balance transactions — balance get Balance History — request body — query
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
created | JSON | Optional | |
created (anyOf 1) | object | Alternative | |
created (anyOf 1).gt | integer | Optional | |
created (anyOf 1).gte | integer | Optional | |
created (anyOf 1).lt | integer | Optional | |
created (anyOf 1).lte | integer | Optional | |
created (anyOf 2) | integer | Alternative | |
currency | string | Optional | Format: currency |
ending_before | string | Optional | Maximum length: 5000 |
expand | array | Optional | |
expand[] | string | Each item | Maximum length: 5000 |
limit | integer | Optional | |
payout | string | Optional | Maximum length: 5000 |
source | string | Optional | Maximum length: 5000 |
starting_after | string | Optional | Maximum length: 5000 |
type | string | Optional | Maximum length: 5000 |
Retrieve a balance transaction — balance get Balance History Id — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Balance transactions represent funds moving through your Stripe account. Stripe creates them for every type of transaction that enters or leaves your Stripe account balance. Related guide: [Balance transaction types](https://docs.stripe.com/reports/balance-transaction-types) |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Gross amount of this transaction (in cents (or local equivalent)). A positive value represents funds charged to another party, and a negative value represents funds sent to another party. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
available_on | JSON | Required within parent | |
available_on (anyOf 1) | integer | Alternative | The date that the transaction's net funds become available in the Stripe balance. Format: unix-time |
available_on (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
balance_type | string | Required within parent | The balance that this transaction impacts. Known values: issuing, payments, refund_and_dispute_prefunding, risk_reserved |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
exchange_rate | JSON | Optional | |
exchange_rate (anyOf 1) | JSON | Alternative | |
exchange_rate (anyOf 1) (anyOf 1) | number | Alternative | If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multiplied by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`. |
exchange_rate (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
exchange_rate (anyOf 2) | null | Alternative | |
fee | JSON | Required within parent | |
fee (anyOf 1) | integer | Alternative | Fees (in cents (or local equivalent)) paid for this transaction. Represented as a positive integer when assessed. |
fee (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
fee_details | array | Required within parent | Detailed breakdown of fees (in cents (or local equivalent)) paid for this transaction. |
fee_details[] | Model | Each item | Expand Retrieve a balance transaction — balance get Balance History Id — response body — fee details item |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
net | JSON | Required within parent | |
net (anyOf 1) | integer | Alternative | Net impact to a Stripe balance (in cents (or local equivalent)). A positive value represents incrementing a Stripe balance, and a negative value decrementing a Stripe balance. You can calculate the net impact of a transaction on a balance by `amount` - `fee` |
net (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: balance_transaction |
reporting_category | string | Required within parent | Learn more about how [reporting categories](https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective. Maximum length: 5000 |
source | JSON | Optional | |
source (anyOf 1) | JSON | Alternative | This transaction relates to the Stripe object. |
source (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
source (anyOf 1) (anyOf 2) | Model | Alternative | Expand Post Application Fees Id Refund — response body |
source (anyOf 1) (anyOf 3) | Model | Alternative | Expand Create a charge — response body |
source (anyOf 1) (anyOf 4) | Model | Alternative | Expand Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: connect collection transfer |
source (anyOf 1) (anyOf 5) | Model | Alternative | Expand Fund a test mode cash balance — response body |
source (anyOf 1) (anyOf 6) | Model | Alternative | Expand Close a dispute — response body |
source (anyOf 1) (anyOf 7) | Model | Alternative | Expand Create an application fee refund — response body |
source (anyOf 1) (anyOf 8) | Model | Alternative | Expand Update an authorization — response body |
source (anyOf 1) (anyOf 9) | Model | Alternative | Expand Create a dispute — response body |
source (anyOf 1) (anyOf 10) | Model | Alternative | Expand Update a transaction — response body |
source (anyOf 1) (anyOf 11) | Model | Alternative | Expand Cancel a payout — response body |
source (anyOf 1) (anyOf 12) | Model | Alternative | Expand Cancel a refund — response body |
source (anyOf 1) (anyOf 13) | Model | Alternative | Expand Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: reserve transaction |
source (anyOf 1) (anyOf 14) | Model | Alternative | Expand Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: tax deducted at source |
source (anyOf 1) (anyOf 15) | Model | Alternative | Expand Cancel a top-up — response body |
source (anyOf 1) (anyOf 16) | Model | Alternative | Expand Create a transfer — response body |
source (anyOf 1) (anyOf 17) | Model | Alternative | Expand Update a reversal — response body |
source (anyOf 2) | null | Alternative | |
status | string | Required within parent | The transaction's net funds status in the Stripe balance, which are either `available` or `pending`. Maximum length: 5000 |
type | string | Required within parent | Transaction type: `tax_fund`, `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `inbound_transfer`, `inbound_transfer_reversal`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_dispute_provisional_credit`, `issuing_dispute_provisional_credit_reversal`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `payout_minimum_balance_hold`, `payout_minimum_balance_release`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `reserve_hold`, `reserve_release`, `stripe_fee`, `stripe_fx_fee`, `stripe_balance_payment_debit`, `stripe_balance_payment_debit_reversal`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, `transfer_refund`, or `fee_credit_funding`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead. Known values: adjustment, advance, advance_funding, anticipation_repayment, application_fee, application_fee_refund, charge, climate_order_purchase, climate_order_refund, connect_collection_transfer, contribution, fee_credit_funding, inbound_transfer, inbound_transfer_reversal, issuing_authorization_hold, issuing_authorization_release, issuing_dispute, issuing_dispute_provisional_credit, issuing_dispute_provisional_credit_reversal, issuing_transaction, obligation_outbound, obligation_reversal_inbound, payment, payment_failure_refund, payment_network_reserve_hold, payment_network_reserve_release, payment_refund, payment_reversal, payment_unreconciled, payout, payout_cancel, payout_failure, payout_minimum_balance_hold, payout_minimum_balance_release, refund, refund_failure, reserve_hold, reserve_release, reserve_transaction, reserved_funds, stripe_balance_payment_debit, stripe_balance_payment_debit_reversal, stripe_fee, stripe_fx_fee, tax_fee, tax_fund, topup, topup_reversal, transfer, transfer_cancel, transfer_failure, transfer_refund |
Referenced models: Post Application Fees Id Refund — response body, Create a charge — response body, Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: connect collection transfer, Fund a test mode cash balance — response body, Close a dispute — response body, Retrieve a balance transaction — balance get Balance History Id — response body — fee details item, Create an application fee refund — response body, Update an authorization — response body, Create a dispute — response body, Update a transaction — response body, Cancel a payout — response body, Cancel a refund — response body, Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: reserve transaction, Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: tax deducted at source, Cancel a top-up — response body, Create a transfer — response body, Update a reversal — response body
Retrieve a balance transaction — balance get Balance History Id — response body — fee details item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Amount of the fee, in cents. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
application | JSON | Optional | |
application (anyOf 1) | string | Alternative | ID of the Connect application that earned the fee. Maximum length: 5000 |
application (anyOf 2) | null | Alternative | |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
type | string | Required within parent | Type of the fee, one of: `application_fee`, `payment_method_passthrough_fee`, `stripe_fee`, `tax`, or `withheld_tax`. Maximum length: 5000 |
Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: connect collection transfer
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Amount transferred, in cents (or local equivalent). |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
destination | JSON | Required within parent | ID of the account that funds are being collected for. |
destination (anyOf 1) | string | Alternative | Maximum length: 5000 |
destination (anyOf 2) | Model | Alternative | Expand Create an account — response body |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: connect_collection_transfer |
Referenced models: Create an account — response body
Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: reserve transaction
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: reserve_transaction |
Retrieve a balance transaction — balance.getBalanceHistoryId — response body — source / This transaction relates to the Stripe object / object: tax deducted at source
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: tax_deducted_at_source |
period_end | JSON | Required within parent | |
period_end (anyOf 1) | integer | Alternative | The end of the invoicing period. This TDS applies to Stripe fees collected during this invoicing period. Format: unix-time |
period_end (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
period_start | JSON | Required within parent | |
period_start (anyOf 1) | integer | Alternative | The start of the invoicing period. This TDS applies to Stripe fees collected during this invoicing period. Format: unix-time |
period_start (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
tax_deduction_account_number | string | Required within parent | The TAN that was supplied to Stripe when TDS was assessed Maximum length: 5000 |
Retrieve balance — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account. The top-level `available` and `pending` comprise your "payments balance." Related guide: [Balances and settlement time](https://docs.stripe.com/payments/balances), [Understanding Connect account balances](https://docs.stripe.com/connect/account-balances) |
available | array | Required within parent | Available funds that you can transfer or pay out automatically by Stripe or explicitly through the [Transfers API](https://docs.stripe.com/api#transfers) or [Payouts API](https://docs.stripe.com/api#payouts). You can find the available balance for each currency and payment type in the `source_types` property. |
available[] | Model | Each item | Expand Retrieve balance — response body — pending item |
connect_reserved | array | Optional | Funds held due to negative balances on connected accounts where [account.controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. You can find the connect reserve balance for each currency and payment type in the `source_types` property. |
connect_reserved[] | Model | Each item | Expand Retrieve balance — response body — pending item |
instant_available | array | Optional | Funds that you can pay out using Instant Payouts. |
instant_available[] | Model | Each item | Expand Retrieve balance — response body — instant available item |
issuing | Model | Optional | Expand Retrieve balance — response body — issuing |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: balance |
pending | array | Required within parent | Funds that aren't available in the balance yet. You can find the pending balance for each currency and each payment type in the `source_types` property. |
pending[] | Model | Each item | Expand Retrieve balance — response body — pending item |
refund_and_dispute_prefunding | Model | Optional | Expand Retrieve balance — response body — refund and dispute prefunding |
Referenced models: Retrieve balance — response body — pending item, Retrieve balance — response body — instant available item, Retrieve balance — response body — issuing, Retrieve balance — response body — refund and dispute prefunding
Retrieve balance — response body — instant available item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Balance amount. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
net_available | array | Optional | Breakdown of balance by destination. |
net_available[] | Model | Each item | Expand Retrieve balance — response body — instant available item net available item |
source_types | Model | Optional | Expand Retrieve balance — response body — pending item source types |
Referenced models: Retrieve balance — response body — pending item source types, Retrieve balance — response body — instant available item net available item
Retrieve balance — response body — instant available item net available item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Net balance amount, subtracting fees from platform-set pricing. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
destination | string | Required within parent | ID of the external account for this net balance (not expandable). Maximum length: 5000 |
source_types | Model | Optional | Expand Retrieve balance — response body — pending item source types |
Referenced models: Retrieve balance — response body — pending item source types
Retrieve balance — response body — issuing
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
available | array | Required within parent | Funds that are available for use. |
available[] | Model | Each item | Expand Retrieve balance — response body — pending item |
Referenced models: Retrieve balance — response body — pending item
Retrieve balance — response body — pending item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | Balance amount. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
source_types | Model | Optional | Expand Retrieve balance — response body — pending item source types |
Referenced models: Retrieve balance — response body — pending item source types
Retrieve balance — response body — pending item source types
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
bank_account | JSON | Optional | |
bank_account (anyOf 1) | integer | Alternative | Amount coming from [legacy US ACH payments](https://docs.stripe.com/ach-deprecated). |
bank_account (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
card | JSON | Optional | |
card (anyOf 1) | integer | Alternative | Amount coming from most payment methods, including cards as well as [non-legacy bank debits](https://docs.stripe.com/payments/bank-debits). |
card (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
fpx | JSON | Optional | |
fpx (anyOf 1) | integer | Alternative | Amount coming from [FPX](https://docs.stripe.com/payments/fpx), a Malaysian payment method. |
fpx (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Retrieve balance — response body — refund and dispute prefunding
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
available | array | Required within parent | Funds that are available for use. |
available[] | Model | Each item | Expand Retrieve balance — response body — pending item |
pending | array | Required within parent | Funds that are pending |
pending[] | Model | Each item | Expand Retrieve balance — response body — pending item |
Referenced models: Retrieve balance — response body — pending item