Operations on Stripe BalanceTransaction objects — the server-side ledger entries that back every Charge, Refund, Transfer, Payout, and fee on a Stripe account.
BalanceTransactions are created by Stripe. There is no client-side
create, update, or delete — the library exposes only retrieve/3,
list/3, and stream!/3. Use the filter params on list/3 to walk
reconciliation reports:
# Every ledger entry that landed in a given payout
{:ok, resp} =
LatticeStripe.BalanceTransaction.list(client, %{"payout" => "po_..."})
# Stream the whole account ledger
client
|> LatticeStripe.BalanceTransaction.stream!(%{"type" => "charge"})
|> Enum.take(1_000)Each BalanceTransaction carries a list of fee_details — individual
platform, Stripe, and tax line items — so reconciliation code can
pattern-match on them without extra calls:
application_fees =
Enum.filter(bt.fee_details, &(&1.type == "application_fee"))The source field is polymorphic (Stripe returns either a string ID
or an expanded object map, spanning 16+ object types). Per D-05 rule 5 it
stays as the raw binary | map() — users who want a typed source compose
LatticeStripe.Charge.from_map/1 (or the relevant resource) themselves.
Stripe API Reference
Summary
Functions
Converts a decoded Stripe API map to a %BalanceTransaction{} struct.
Lists BalanceTransactions with optional filters.
Like list/3 but raises LatticeStripe.Error on failure.
Retrieves a BalanceTransaction by ID.
Like retrieve/3 but raises LatticeStripe.Error on failure.
Returns a lazy stream of all BalanceTransactions matching the given filters (auto-pagination). Raises on any page failure.
Types
@type t() :: %LatticeStripe.BalanceTransaction{ amount: integer() | nil, available_on: integer() | nil, balance_type: String.t() | nil, created: integer() | nil, currency: String.t() | nil, description: String.t() | nil, exchange_rate: number() | nil, extra: map(), fee: integer() | nil, fee_details: [LatticeStripe.BalanceTransaction.FeeDetail.t()] | nil, id: String.t() | nil, net: integer() | nil, object: String.t(), reporting_category: String.t() | nil, source: struct() | String.t() | nil, status: atom() | String.t() | nil, type: atom() | String.t() | nil }
A Stripe BalanceTransaction object.
See the Stripe BalanceTransaction API for field definitions.
Functions
Converts a decoded Stripe API map to a %BalanceTransaction{} struct.
fee_detailsis decoded into a list of%BalanceTransaction.FeeDetail{}.sourceis kept as the rawbinary | map()(polymorphic per D-05 rule 5).- Unknown top-level fields survive in
:extra.
@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists BalanceTransactions with optional filters.
Supported Stripe filters (all optional, pass-through):
payout, source, type, currency, created.
Returns {:ok, %Response{data: %List{data: [%BalanceTransaction{}, ...]}}}.
@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/3 but raises LatticeStripe.Error on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves a BalanceTransaction by ID.
Sends GET /v1/balance_transactions/:id and returns
{:ok, %BalanceTransaction{}}. Raises ArgumentError (pre-network) if
id is empty.
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like retrieve/3 but raises LatticeStripe.Error on failure.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Returns a lazy stream of all BalanceTransactions matching the given filters (auto-pagination). Raises on any page failure.