This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account. You can also retrieve the balance history, which contains a list of transactions that contributed to the balance (charges, payouts, and so forth).
openapi: 3.0.0
info:
title: Stripe Balance API
description: >-
This is an object representing your Stripe balance. You can retrieve it to
see the balance currently on your Stripe account. You can also retrieve the
balance history, which contains a list of transactions that contributed to
the balance (charges, payouts, and so forth).
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/balance:
get:
description: >-
<p>Retrieves the current account balance, based on the authentication
that was used to make the request.
For a sample request, see <a href="/docs/connect/account-balances#accounting-for-negative-balances">Accounting for negative balances</a>.</p>
operationId: getBalance
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBalanceRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/balance'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Balance
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Get
/v1/balance/history:
get:
description: >-
<p>Returns a list of transactions that have contributed to the Stripe
account balance (e.g., charges, transfers, and so forth). The
transactions are returned in sorted order, with the most recent
transactions appearing first.</p>
<p>Note that this endpoint was previously called “Balance history” and
used the path <code>/v1/balance/history</code>.</p>
operationId: getBalanceHistory
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
Only return transactions in a certain currency. 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).
in: query
name: currency
required: false
schema:
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
For automatic Stripe payouts only, only returns transactions that
were paid out on the specified payout ID.
in: query
name: payout
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Only returns the original transaction.
in: query
name: source
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Only returns transactions of the given type. One of: `adjustment`,
`advance`, `advance_funding`, `anticipation_repayment`,
`application_fee`, `application_fee_refund`, `charge`,
`climate_order_purchase`, `climate_order_refund`,
`connect_collection_transfer`, `contribution`,
`issuing_authorization_hold`, `issuing_authorization_release`,
`issuing_dispute`, `issuing_transaction`, `obligation_inbound`,
`obligation_outbound`, `obligation_reversal_inbound`,
`obligation_reversal_outbound`, `obligation_payout`,
`obligation_payout_failure`, `payment`, `payment_failure_refund`,
`payment_network_reserve_hold`, `payment_network_reserve_release`,
`payment_refund`, `payment_reversal`, `payment_unreconciled`,
`payout`, `payout_cancel`, `payout_failure`, `refund`,
`refund_failure`, `reserve_transaction`, `reserved_funds`,
`stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`,
`transfer`, `transfer_cancel`, `transfer_failure`, or
`transfer_refund`.
in: query
name: type
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBalanceHistoryRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/BalanceTransactionsList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Balance History
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Get
- History
/v1/balance/history/{id}:
get:
description: >-
<p>Retrieves the balance transaction with the given ID.</p>
<p>Note that this endpoint previously used the path
<code>/v1/balance/history/:id</code>.</p>
operationId: getBalanceHistoryId
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBalanceHistoryIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Balance History Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Get
- History
- Identifiers
/v1/balance_transactions:
get:
description: >-
<p>Returns a list of transactions that have contributed to the Stripe
account balance (e.g., charges, transfers, and so forth). The
transactions are returned in sorted order, with the most recent
transactions appearing first.</p>
<p>Note that this endpoint was previously called “Balance history” and
used the path <code>/v1/balance/history</code>.</p>
operationId: getBalanceTransactions
parameters:
- explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: >-
Only return transactions in a certain currency. 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).
in: query
name: currency
required: false
schema:
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
For automatic Stripe payouts only, only returns transactions that
were paid out on the specified payout ID.
in: query
name: payout
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Only returns the original transaction.
in: query
name: source
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: >-
Only returns transactions of the given type. One of: `adjustment`,
`advance`, `advance_funding`, `anticipation_repayment`,
`application_fee`, `application_fee_refund`, `charge`,
`climate_order_purchase`, `climate_order_refund`,
`connect_collection_transfer`, `contribution`,
`issuing_authorization_hold`, `issuing_authorization_release`,
`issuing_dispute`, `issuing_transaction`, `obligation_inbound`,
`obligation_outbound`, `obligation_reversal_inbound`,
`obligation_reversal_outbound`, `obligation_payout`,
`obligation_payout_failure`, `payment`, `payment_failure_refund`,
`payment_network_reserve_hold`, `payment_network_reserve_release`,
`payment_refund`, `payment_reversal`, `payment_unreconciled`,
`payout`, `payout_cancel`, `payout_failure`, `refund`,
`refund_failure`, `reserve_transaction`, `reserved_funds`,
`stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`,
`transfer`, `transfer_cancel`, `transfer_failure`, or
`transfer_refund`.
in: query
name: type
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBalanceTransactionsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/BalanceTransactionsList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Balance Transactions
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Get
- Transactions
/v1/balance_transactions/{id}:
get:
description: >-
<p>Retrieves the balance transaction with the given ID.</p>
<p>Note that this endpoint previously used the path
<code>/v1/balance/history/:id</code>.</p>
operationId: getBalanceTransactionsId
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: id
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetBalanceTransactionsIdRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/balance_transaction'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Balance Transactions Id
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Balance
- Get
- Identifiers
- Transactions
components:
schemas:
balance:
description: >-
This is an object representing your Stripe balance. You can retrieve it
to see
the balance currently on your Stripe account.
You can also retrieve the balance history, which contains a list of
[transactions](https://stripe.com/docs/reporting/balance-transaction-types)
that contributed to the balance
(charges, payouts, and so forth).
The available and pending amounts for each currency are broken down
further by
payment source types.
Related guide: [Understanding Connect account
balances](https://stripe.com/docs/connect/account-balances)
properties:
available:
description: >-
Available funds that you can transfer or pay out automatically by
Stripe or explicitly through the [Transfers
API](https://stripe.com/docs/api#transfers) or [Payouts
API](https://stripe.com/docs/api#payouts). You can find the
available balance for each currency and payment type in the
`source_types` property.
items:
$ref: '#/components/schemas/balance_amount'
type: array
connect_reserved:
description: >-
Funds held due to negative balances on connected Custom accounts.
You can find the connect reserve balance for each currency and
payment type in the `source_types` property.
items:
$ref: '#/components/schemas/balance_amount'
type: array
instant_available:
description: Funds that you can pay out using Instant Payouts.
items:
$ref: '#/components/schemas/balance_amount_net'
type: array
issuing:
$ref: '#/components/schemas/balance_detail'
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- balance
type: string
pending:
description: >-
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.
items:
$ref: '#/components/schemas/balance_amount'
type: array
required:
- available
- livemode
- object
- pending
title: Balance
type: object
x-expandableFields:
- available
- connect_reserved
- instant_available
- issuing
- pending
x-resourceId: balance
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
balance_transaction:
description: >-
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://stripe.com/docs/reports/balance-transaction-types)
properties:
amount:
description: >-
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.
type: integer
available_on:
description: >-
The date that the transaction's net funds become available in the
Stripe balance.
format: unix-time
type: integer
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
currency:
description: >-
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).
type: string
description:
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
maxLength: 5000
nullable: true
type: string
exchange_rate:
description: >-
If applicable, this transaction uses an exchange rate. If money
converts from currency A to currency B, then the `amount` in
currency A, multipled 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`.
nullable: true
type: number
fee:
description: >-
Fees (in cents (or local equivalent)) paid for this transaction.
Represented as a positive integer when assessed.
type: integer
fee_details:
description: >-
Detailed breakdown of fees (in cents (or local equivalent)) paid for
this transaction.
items:
$ref: '#/components/schemas/fee'
type: array
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
net:
description: >-
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`
type: integer
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- balance_transaction
type: string
reporting_category:
description: >-
Learn more about how [reporting
categories](https://stripe.com/docs/reports/reporting-categories)
can help you understand balance transactions from an accounting
perspective.
maxLength: 5000
type: string
source:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application_fee'
- $ref: '#/components/schemas/charge'
- $ref: '#/components/schemas/connect_collection_transfer'
- $ref: '#/components/schemas/customer_cash_balance_transaction'
- $ref: '#/components/schemas/dispute'
- $ref: '#/components/schemas/fee_refund'
- $ref: '#/components/schemas/issuing.authorization'
- $ref: '#/components/schemas/issuing.dispute'
- $ref: '#/components/schemas/issuing.transaction'
- $ref: '#/components/schemas/payout'
- $ref: '#/components/schemas/platform_tax_fee'
- $ref: '#/components/schemas/refund'
- $ref: '#/components/schemas/reserve_transaction'
- $ref: '#/components/schemas/tax_deducted_at_source'
- $ref: '#/components/schemas/topup'
- $ref: '#/components/schemas/transfer'
- $ref: '#/components/schemas/transfer_reversal'
description: This transaction relates to the Stripe object.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application_fee'
- $ref: '#/components/schemas/charge'
- $ref: '#/components/schemas/connect_collection_transfer'
- $ref: '#/components/schemas/customer_cash_balance_transaction'
- $ref: '#/components/schemas/dispute'
- $ref: '#/components/schemas/fee_refund'
- $ref: '#/components/schemas/issuing.authorization'
- $ref: '#/components/schemas/issuing.dispute'
- $ref: '#/components/schemas/issuing.transaction'
- $ref: '#/components/schemas/payout'
- $ref: '#/components/schemas/platform_tax_fee'
- $ref: '#/components/schemas/refund'
- $ref: '#/components/schemas/reserve_transaction'
- $ref: '#/components/schemas/tax_deducted_at_source'
- $ref: '#/components/schemas/topup'
- $ref: '#/components/schemas/transfer'
- $ref: '#/components/schemas/transfer_reversal'
x-stripeBypassValidation: true
status:
description: >-
The transaction's net funds status in the Stripe balance, which are
either `available` or `pending`.
maxLength: 5000
type: string
type:
description: >-
Transaction type: `adjustment`, `advance`, `advance_funding`,
`anticipation_repayment`, `application_fee`,
`application_fee_refund`, `charge`, `climate_order_purchase`,
`climate_order_refund`, `connect_collection_transfer`,
`contribution`, `issuing_authorization_hold`,
`issuing_authorization_release`, `issuing_dispute`,
`issuing_transaction`, `obligation_inbound`, `obligation_outbound`,
`obligation_reversal_inbound`, `obligation_reversal_outbound`,
`obligation_payout`, `obligation_payout_failure`, `payment`,
`payment_failure_refund`, `payment_network_reserve_hold`,
`payment_network_reserve_release`, `payment_refund`,
`payment_reversal`, `payment_unreconciled`, `payout`,
`payout_cancel`, `payout_failure`, `refund`, `refund_failure`,
`reserve_transaction`, `reserved_funds`, `stripe_fee`,
`stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`,
`transfer_cancel`, `transfer_failure`, or `transfer_refund`. 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.
enum:
- adjustment
- advance
- advance_funding
- anticipation_repayment
- application_fee
- application_fee_refund
- charge
- climate_order_purchase
- climate_order_refund
- connect_collection_transfer
- contribution
- issuing_authorization_hold
- issuing_authorization_release
- issuing_dispute
- issuing_transaction
- obligation_inbound
- obligation_outbound
- obligation_payout
- obligation_payout_failure
- obligation_reversal_inbound
- obligation_reversal_outbound
- payment
- payment_failure_refund
- payment_network_reserve_hold
- payment_network_reserve_release
- payment_refund
- payment_reversal
- payment_unreconciled
- payout
- payout_cancel
- payout_failure
- refund
- refund_failure
- reserve_transaction
- reserved_funds
- stripe_fee
- stripe_fx_fee
- tax_fee
- topup
- topup_reversal
- transfer
- transfer_cancel
- transfer_failure
- transfer_refund
type: string
required:
- amount
- available_on
- created
- currency
- fee
- fee_details
- id
- net
- object
- reporting_category
- status
- type
title: BalanceTransaction
type: object
x-expandableFields:
- fee_details
- source
x-resourceId: balance_transaction
GetBalanceRequest:
type: object
properties: {}
GetBalanceHistoryRequest:
type: object
properties: {}
BalanceTransactionsList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/balance_transaction'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/balance_transactions
type: string
GetBalanceHistoryIdRequest:
type: object
properties: {}
GetBalanceTransactionsRequest:
type: object
properties: {}
GetBalanceTransactionsIdRequest:
type: object
properties: {}
securitySchemes:
basicAuth:
description: >-
Basic HTTP authentication. Allowed headers-- Authorization: Basic
<api_key> | Authorization: Basic <base64 hash of `api_key:`>
scheme: basic
type: http
bearerAuth:
bearerFormat: auth-scheme
description: >-
Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
<api_key>
scheme: bearer
type: http
tags:
- name: Balance
- name: Get
- name: History
- name: Identifiers
- name: Transactions