Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
    API v2
    API keys
    Stripe-Context header
    Daily changelog
    Rate limits
    Automated testing
    Metadata
    Expanding responses
      Use cases
    Pagination
    Domains and IP addresses
    Search
    Error handling
    Error codes
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuilding with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsAPIExpanding responses

Use cases for expanding responses

Learn how the expand attribute helps you perform common tasks.

Copy page

See the Stripe fee for a given payment

You can check the processing fees for a payment after the payment is processed and the balance transaction is created. Stripe automatically creates this balance transaction in the background. The charge.updated event includes a reference to the balance transaction through the balance_transaction property (for example, txn_123), indicating that the balance transaction has been created and is ready for use.

Instead of looking up the balance transaction separately, you can retrieve it in a single call using expand. For example:

Command Line
curl
curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d "expand[]"="latest_charge.balance_transaction" \ -G

Users on API version 2022-08-01 or older:

Command Line
curl
curl https://api.stripe.com/v1/payment_intents/pi_1Gpl8kLHughnNhxyIb1RvRTu \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d "expand[]"="charges.data.balance_transaction" \ -G

Note

A payment intent must be captured and have a status of succeeded for the Stripe fees to be available.

See the charges included in a payout

Every automatic payout is tied to historical changes to the balance of your Stripe account. The API records these historical changes as balance transactions, which you can retrieve using List Balance Transactions. From a list of balance transactions, you can expand the source property to gather information on what triggered the change to the account balance (Charge, Refund, Transfer, and so on). For example:

Command Line
curl
curl https://api.stripe.com/v1/balance_transactions \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d payout=po_1Gl3ZLLHughnNhxyDrOia0vI \ -d type=charge \ -d "expand[]"="data.source" \ -G

Note

You can only retrieve balance transaction history on automatic payouts. If you have manual payouts enabled, you must track transaction history on your own.

Learn more about payout reconciliation.

If you’re using Connect with destination charges, you can retrieve the same information on behalf of your connected accounts. One difference is that destination charges involve both a transfer and a linked payment (in the form of a Charge object) to move funds to a connected account. So when listing the balance transactions bundled in your connected account’s payouts, each balance transaction’s source is linked to the transfer’s payment rather than the originating Charge. To retrieve the originating Charge, you need to expand a payment’s linked transfer through the source_transfer property; and from there, expand the transfer’s source_transaction property:

Command Line
curl
curl https://api.stripe.com/v1/balance_transactions \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d payout=po_1G7bnaD2wdkPsFGzdVOqU44u \ -d type=payment \ -d "expand[]"="data.source.source_transfer.source_transaction" \ -H "Stripe-Account: acct_1G7PaoD2wdkPsFGz" \ -G
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc