BalanceTransaction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stripe/main/json-schema/stripe-balance-transaction-schema.json",
  "title": "BalanceTransaction",
  "description": "Balance transactions represent funds moving through your Stripe account.\nStripe creates them for every type of transaction that enters or leaves your Stripe account balance.\n\nRelated guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stripe-balance-api-openapi.yml#/components/schemas/balance_transaction",
  "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,
      "type": [
        "string",
        "null"
      ]
    },
    "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`.",
      "type": [
        "number",
        "null"
      ]
    },
    "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": "#/$defs/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": "#/$defs/application_fee"
        },
        {
          "$ref": "#/$defs/charge"
        },
        {
          "$ref": "#/$defs/connect_collection_transfer"
        },
        {
          "$ref": "#/$defs/customer_cash_balance_transaction"
        },
        {
          "$ref": "#/$defs/dispute"
        },
        {
          "$ref": "#/$defs/fee_refund"
        },
        {
          "$ref": "#/$defs/issuing.authorization"
        },
        {
          "$ref": "#/$defs/issuing.dispute"
        },
        {
          "$ref": "#/$defs/issuing.transaction"
        },
        {
          "$ref": "#/$defs/payout"
        },
        {
          "$ref": "#/$defs/platform_tax_fee"
        },
        {
          "$ref": "#/$defs/refund"
        },
        {
          "$ref": "#/$defs/reserve_transaction"
        },
        {
          "$ref": "#/$defs/tax_deducted_at_source"
        },
        {
          "$ref": "#/$defs/topup"
        },
        {
          "$ref": "#/$defs/transfer"
        },
        {
          "$ref": "#/$defs/transfer_reversal"
        }
      ],
      "description": "This transaction relates to the Stripe object.",
      "x-expansionResources": {
        "oneOf": [
          {
            "$ref": "#/$defs/application_fee"
          },
          {
            "$ref": "#/$defs/charge"
          },
          {
            "$ref": "#/$defs/connect_collection_transfer"
          },
          {
            "$ref": "#/$defs/customer_cash_balance_transaction"
          },
          {
            "$ref": "#/$defs/dispute"
          },
          {
            "$ref": "#/$defs/fee_refund"
          },
          {
            "$ref": "#/$defs/issuing.authorization"
          },
          {
            "$ref": "#/$defs/issuing.dispute"
          },
          {
            "$ref": "#/$defs/issuing.transaction"
          },
          {
            "$ref": "#/$defs/payout"
          },
          {
            "$ref": "#/$defs/platform_tax_fee"
          },
          {
            "$ref": "#/$defs/refund"
          },
          {
            "$ref": "#/$defs/reserve_transaction"
          },
          {
            "$ref": "#/$defs/tax_deducted_at_source"
          },
          {
            "$ref": "#/$defs/topup"
          },
          {
            "$ref": "#/$defs/transfer"
          },
          {
            "$ref": "#/$defs/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"
  ],
  "type": "object",
  "x-expandableFields": [
    "fee_details",
    "source"
  ],
  "x-resourceId": "balance_transaction"
}