# `MishkaPay.Customer.BalanceTransaction`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/nofile#L1)

One change of a customer's balance at the provider: store credit given, a debit added, or
credit used on a bill. Made with `MishkaPay.adjust_customer_balance/5` and listed with
`MishkaPay.list_customer_balance/4`. A guarded_struct.

The sign is the provider's: below zero is credit, money the seller owes the customer, taken off
their next bills; above zero is a debit added to their next bill. At Stripe a customer's
balance is in one currency.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:customer_id`: the provider customer.
  * `:amount`: a `Money`, below zero to give credit.
  * `:description`: why, for the seller and the customer.
  * `:reference`: the caller's own id for this change, such as a support ticket. It makes the
    idempotency key, so the same reference never changes the balance twice, and it comes back
    on it.

What the provider fills in: `:id` (`cbtxn_...` at Stripe), `:ending_balance` (the balance after
it), `:type` (its own name for it, such as `"adjustment"` or `"applied_to_invoice"`),
`:invoice_id` when a bill used it, and `:created_at`.

# `t`

```elixir
@type t() :: %MishkaPay.Customer.BalanceTransaction{
  amount: Money.t(),
  created_at: DateTime.t() | nil,
  customer_id: String.t(),
  description: String.t() | nil,
  ending_balance: Money.t() | nil,
  id: String.t() | nil,
  invoice_id: String.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  tenant: term() | nil,
  type: String.t() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:customer_id` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:amount` | `Money.t()` | yes |  |  | validator `{MishkaPay.Money, :signed_field}` |
| `:description` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=350)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:ending_balance` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :signed_field}` |
| `:type` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:invoice_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Customer.BalanceTransaction{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

---

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