# `LatticeStripe.BalanceTransaction`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v2.2.2/lib/lattice_stripe/balance_transaction.ex#L1)

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

https://docs.stripe.com/api/balance_transactions

# `t`

```elixir
@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](https://docs.stripe.com/api/balance_transactions/object)
for field definitions.

# `from_map`

```elixir
@spec from_map(map() | nil) :: t() | nil
```

Converts a decoded Stripe API map to a `%BalanceTransaction{}` struct.

- `fee_details` is decoded into a list of `%BalanceTransaction.FeeDetail{}`.
- `source` is kept as the raw `binary | map()` (polymorphic per D-05 rule 5).
- Unknown top-level fields survive in `:extra`.

# `list`

```elixir
@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{}, ...]}}}`.

# `list!`

```elixir
@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
```

Like `list/3` but raises `LatticeStripe.Error` on failure.

# `retrieve`

```elixir
@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.

# `retrieve!`

```elixir
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
```

Like `retrieve/3` but raises `LatticeStripe.Error` on failure.

# `stream!`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*