# `LatticeStripe.Balance`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v1.1.0/lib/lattice_stripe/balance.ex#L1)

Stripe Balance singleton.

`Balance.retrieve(client)` fetches the **platform** balance.
`Balance.retrieve(client, stripe_account: "acct_123")` fetches the
**connected account's** balance via the per-request `Stripe-Account` header —
this is the ONLY distinction between the two reads.

> #### Reconciliation loop antipattern {: .warning}
>
> Code that walks every connected account in a loop MUST pass the
> `stripe_account:` opt on each call. Calling `Balance.retrieve(client)`
> with no opts inside such a loop returns the platform balance every time
> and silently produces wrong reconciliation totals.

## Examples

    # Platform balance
    {:ok, balance} = LatticeStripe.Balance.retrieve(client)

    # Connected account balance (per-request override)
    {:ok, balance} =
      LatticeStripe.Balance.retrieve(client, stripe_account: "acct_123")

    # Read available USD balance
    [usd] = Enum.filter(balance.available, &(&1.currency == "usd"))
    IO.puts("Available USD: #{usd.amount}")

    # Read source-type breakdown
    IO.puts("From cards: #{usd.source_types.card}")

## Module surface

Balance is a **singleton** — it has no `id`, no `list/1`, no
`create/2`, `update/3`, or `delete/2`. The only operations are
`retrieve/2` and `retrieve!/2`.

## Stripe API Reference

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

# `t`

```elixir
@type t() :: %LatticeStripe.Balance{
  available: [LatticeStripe.Balance.Amount.t()] | nil,
  connect_reserved: [LatticeStripe.Balance.Amount.t()] | nil,
  extra: map(),
  instant_available: [LatticeStripe.Balance.Amount.t()] | nil,
  issuing: map() | nil,
  livemode: boolean() | nil,
  object: String.t(),
  pending: [LatticeStripe.Balance.Amount.t()] | nil
}
```

A Stripe Balance object.

# `retrieve`

```elixir
@spec retrieve(
  LatticeStripe.Client.t(),
  keyword()
) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
```

Retrieves the Stripe Balance.

Sends `GET /v1/balance` and returns `{:ok, %Balance{}}`.

Pass `stripe_account: "acct_..."` in `opts` to retrieve a connected
account's balance via the per-request `Stripe-Account` header.

# `retrieve!`

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

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

---

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