Balance Transactions

Balance transactions make reporting a piece of cake. From basic charges to basic payouts, balance transactions are designed for any form of transaction that enters or exits your Tilled account balances. Learn more today!

When a payment is first received, it is initially reflected as a pending balance (less any Tilled fees). This balance becomes available according to your payout schedule. The status attribute on balance transactions indicates the type of the balance.

Balance Transaction Source

A source_id field in balance transactions contains the ID of the related Tilled object. The API can be used to obtain more information about the payment activity that resulted in the creation of the Balance transaction. For example, if the type of a given Balance transaction is type=charge and the source_id=ch_123..., you could get the charge details from this request by passing in the charge ID (ch_123...).


Balance transactions can be generated by a variety of scenarios, but we'll look at a few examples below. We'll assume the fee schedule for the merchants who processed these card transactions was set at 2.9 percent + $0.30. A $100 charge would result in fees of $3.20 (2.9 percent = $2.90 + $0.30 = $3.20).

Basic Charge

Payment intent id=pi xxx amount=10000 Charge id=ch xxx payment_intent_id=pi_xxx amount_captured=10000 Balance transaction type= charge source_id=ch_xxx amount=10000 fee=320 net=9680 {$100.00} {$3.20} {$96.80} ATTRIBUTES ATTRIBUTES ATTRIBUTES Basic Charge

Partial Charge

Partial charge with manual capture ($100 authorized, $80 captured, $20 refunded)

Two balance transactions are created here and the type=charge one is for the full amount ($100). Note: The charge balance transaction is created at time of capture. The authorization does not create a balance transaction. Payment intent id=pi_xxx amount=10000 capture_method= manual Balance amount=8000 fee=262 net=7738 Charge id=ch_xxx payment_intent_id=pi_xxx amount_captured=8000 amount_refunded=2000 Balance transaction type= charge source_id=ch_xxx amount=10000 fee=320 net=9680 {$100.00} {$3.20} {$96.80} {$80.00} {$2.62} {$77.38} Balance transaction type= refund source_id= re_xxx amount=-2000 fee=-.58 net=-1942 {-$20.00} {-$0.58} {-$19.42} Refund id= re_xxx charge_id=ch_xxx payment_intent_id=pi_xxx amount=2000 Note: This is an auth reversal {$100.00} ATTRIBUTES SUM ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES Partial Charge

Basic Payout (3 x $100 charges)

The payout_id=null on balance transactions until a payout is created, at which time, all the related balance transactions are updated. Charge id= ch_xxx1 payment_intent_id=pi_xxx1 amount_captured=10000 Balance transaction type= charge source_id=ch_xxx1 amount=10000 fee=320 net=9680 payout_id=po_xxx {$100.00} {$3.20} {$96.80} Charge id=ch_xxx2 payment_intent_id=pi_xxx2 amount_captured=10000 Balance transaction type= charge source_id=ch_xxx2 amount=10000 fee=320 net=9680 payout_id=po_xxx {$100.00} {$3.20} {$96.80} Payout id=po_xxx amount=29040 Balance transaction type= charge source_id=po_xxx amount=-29040 fee=0 net=-29040 payout_id= null {$-290.40} {$-290.40} {$290.40} Charge id=ch_xxx3 payment_intent_id=pi_xxx3 amount_captured=10000 Balance transaction type= charge source_id=ch_xxx3 amount=10000 fee=320 net=9680 payout_id=po_xxx {$100.00} {$3.20} {$96.80} Balance amount=8000 fee=262 net=7738 {$80.00} {$2.62} {$77.38} ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES ATTRIBUTES SUM Basic Payout (3 x $100 charges)