# `MishkaPay.Invoice`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/invoice.ex#L5)

One bill, as `MishkaPay.list_invoices/3` lists them and `MishkaPay.fetch_invoice/3` reads one; a
preview of the next one from `MishkaPay.preview_subscription_change/1`. A guarded_struct the
provider fills in.

  * `:id`: the provider's id (`in_...` at Stripe); `:subscription_id`: whose bill.
  * `:status`: `:draft`, `:open` (waiting to be paid), `:paid`, `:uncollectible` or `:void`.
  * `:amount_due`, `:amount_paid`: what it asks and what was paid, as `Money`; `:total`, all of
    it after discounts and tax; `:amount_tax`, the tax in it.
  * `:lines`: what it bills, each a `MishkaPay.Invoice.Lines` (see below).
  * `:customer_id`: who it bills.
  * `:period_start`, `:period_end`: the period it bills.
  * `:hosted_url`, `:pdf_url`: the provider's page and PDF of the bill, for the buyer.
  * `:payment_id`: the payment that paid it, when the provider names one.
  * `:number`: the bill's number once finalized; `:collection`: `:charge_automatically` or
    `:send_invoice`; `:due_at`: when a sent bill is due; `:description`; `:reference`: the
    caller's own id from `MishkaPay.Invoice.Draft`.
  * `:created_at`: when the provider made it.

## Lines

Each of `:lines` is a `MishkaPay.Invoice.Lines`, a sub_field of this struct: what the bill
charges, how much and for which period. `:id` (`il_...` at Stripe) names it in a credit note's
lines (`MishkaPay.CreditNote`); `:description`, `:amount` (below zero for a credit),
`:quantity`, `:price_id`, `:period_start` and `:period_end`. A line with `proration: true` is
the credit for time not used on the old plan, or the charge for the rest of the period on the
new one, after a `MishkaPay.change_subscription/1`.

# `t`

```elixir
@type t() :: %MishkaPay.Invoice{
  amount_due: Money.t() | nil,
  amount_paid: Money.t() | nil,
  amount_tax: Money.t() | nil,
  collection: (:charge_automatically | :send_invoice) | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  description: String.t() | nil,
  draft: MishkaPay.Invoice.Draft.t() | nil,
  due_at: DateTime.t() | nil,
  hosted_url: String.t() | nil,
  id: String.t(),
  item: MishkaPay.Invoice.Item.t() | nil,
  lines: [MishkaPay.Invoice.Lines.t()] | nil,
  number: String.t() | nil,
  payment_id: String.t() | nil,
  pdf_url: String.t() | nil,
  period_end: DateTime.t() | nil,
  period_start: DateTime.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  status: atom() | nil,
  subscription_id: String.t() | nil,
  total: Money.t() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `validate(not_nil_value, string)` |
| `:id` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:subscription_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:status` | `atom()` \| `nil` | no |  |  | `validate(enum=Atom[draft::open::paid::uncollectible::void])` |
| `:amount_due` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_paid` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:total` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_tax` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:lines` | [`[MishkaPay.Invoice.Lines.t()]`](`t:MishkaPay.Invoice.Lines.t/0`) \| `nil` | no | `[]` |  | `validate(list)` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:period_start` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:period_end` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:hosted_url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:pdf_url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:payment_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:number` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:collection` | `:charge_automatically` \| `:send_invoice` \| `nil` | no |  |  | `validate(enum=Atom[charge_automatically::send_invoice])` |
| `:due_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:description` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:draft` | [`MishkaPay.Invoice.Draft.t()`](`t:MishkaPay.Invoice.Draft.t/0`) \| `nil` | no |  | A bill to make for a customer, outside any subscription, with `MishkaPay.create_invoice/1`: a service sold by hand, an order paid later. The provider makes it as a draft and answers it as a `MishkaPay.Invoice`; `MishkaPay.finalize_invoice/3` opens it for payment, `MishkaPay.send_invoice/3` emails it, and `MishkaPay.pay_invoice/4`, `void_invoice/3`, `mark_invoice_uncollectible/3` and `delete_invoice/3` end it. A guarded_struct. |  |
| `:item` | [`MishkaPay.Invoice.Item.t()`](`t:MishkaPay.Invoice.Item.t/0`) \| `nil` | no |  | 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. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `item_price`

```elixir
@spec item_price(MishkaPay.Invoice.Item.t()) :: MishkaPay.Price.t()
```

What a new `MishkaPay.Invoice.Item` charges, as a `MishkaPay.Price` (its catalog price, or its
name, amount and quantity): the line a provider's bill takes.

# `keys`

# `keys`

---

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