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

One charge for a customer kept on its own, outside `MishkaPay.create_invoice/1`: a setup fee, an
extra seat, a late fee. Left off any bill it waits (pending) and goes on the customer's next
bill, a subscription's renewal or a one-off bill; given `:invoice_id` it goes on that draft
bill. Made with `MishkaPay.create_invoice_item/1`, changed with
`MishkaPay.update_invoice_item/1`, listed with `MishkaPay.list_invoice_items/3` and removed
with `MishkaPay.delete_invoice_item/3`. A guarded_struct.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:customer_id`: whose bill it goes on.
  * `:invoice_id`: a draft bill to put it on; left out, it waits for the customer's next bill.
  * What it charges: a catalog price by `:price_id`, or a `:name` with an `:amount` (the price
    of one); `:quantity` (1 unless given), `:tax_code`, `:tax_behavior` and `:tax_rate_ids`
    (the seller's own `MishkaPay.TaxRate`s on it) as on a `MishkaPay.Price`.
  * `:reference`: the caller's own id for it; it makes the idempotency key, so the same reference
    never charges twice, and it comes back on it.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:id` (`ii_...` at Stripe), `:total` (the amount times the quantity;
below zero for a credit), `:period_start` and `:period_end`, `:created_at`.

A change (`:id` given) names only what it changes: `:name`, `:amount` (in the item's own
currency), `:quantity`, `:price_id`, the tax fields, `:metadata`. An item stays on its customer
and bill; once its bill is finalized it cannot change or go.

# `t`

```elixir
@type t() :: %MishkaPay.Invoice.Item{
  amount: Money.t() | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  id: String.t() | nil,
  invoice_id: String.t() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  period_end: DateTime.t() | nil,
  period_start: DateTime.t() | nil,
  price_id: String.t() | nil,
  provider: String.t(),
  quantity: pos_integer() | nil,
  reference: String.t() | nil,
  tax_behavior: (:inclusive | :exclusive) | nil,
  tax_code: String.t() | nil,
  tax_rate_ids: list() | nil,
  tenant: term() | nil,
  total: Money.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 |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:invoice_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:price_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=500)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :signed_field}` |
| `:quantity` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:tax_code` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=100)` |
| `:tax_behavior` | `:inclusive` \| `:exclusive` \| `nil` | no |  |  | `validate(enum=Atom[inclusive::exclusive])`<br>validator `{MishkaPay.Price, :tax_behavior}` |
| `:tax_rate_ids` | `list()` \| `nil` | no |  |  | `sanitize(each=[trim]) validate(list, each=[string, not_empty])` |
| `:total` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :signed_field}` |
| `:period_start` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:period_end` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

A sample %MishkaPay.Invoice.Item{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

---

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