Stripe Balance Transactions API

openapi: 3.0.0
info:
  title: Stripe Accounts Account Balance Transactions API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Balance Transactions
paths:
  /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.
      tags:
      - Balance 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.
      tags:
      - Balance Transactions
components:
  schemas:
    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
    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
    GetBalanceTransactionsRequest:
      type: object
      properties: {}
    GetBalanceTransactionsIdRequest:
      type: object
      properties: {}