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

A credit note: the tax-correct way to take back part or all of a finalized bill, instead of
changing it. Made with `MishkaPay.create_credit_note/1` (try it first with
`MishkaPay.preview_credit_note/1`), read with `MishkaPay.fetch_credit_note/3`, listed with
`MishkaPay.list_credit_notes/3` and `MishkaPay.list_credit_note_lines/4`, and ended with
`MishkaPay.void_credit_note/3`. A guarded_struct.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:invoice_id`: the finalized bill it credits (`MishkaPay.Invoice`).
  * What it credits, one of them: an `:amount` of the whole bill, or `:lines`, each a
    `MishkaPay.CreditNote.Lines` (a line of the bill, or a line of its own).
  * `:reason`: `:duplicate`, `:fraudulent`, `:order_change` or `:product_unsatisfactory`.
  * Where the money goes, on a paid bill: `:refund_amount` back to the buyer's card,
    `:credit_amount` onto the customer's balance (taken off their next bills),
    `:out_of_band_amount` given back outside the provider. Together they make the note's
    amount. On an open bill the note lowers what is still due instead.
  * `:memo`: text on the note the buyer sees.
  * `:reference`: the caller's own id for it; it makes the idempotency key, so the same
    reference never credits twice, and it comes back on it.
  * `:metadata`: extra pairs, string keys to string values.

Every amount is in the bill's currency.

What the provider fills in: `:id` (`cn_...` at Stripe), `:number`, `:status` (`:issued` or
`:void`), `:type` (`:pre_payment` when the bill was open, `:post_payment` when it was paid,
`:mixed`), `:customer_id`, `:amount` (all of it, tax included), `:amount_tax`, the `:lines`,
`:refund_ids` (the refunds it made), `:pdf_url`, `:voided_at` and `:created_at`. A preview
answers the same, from a note not made.

## Lines

Each of `:lines` is a `MishkaPay.CreditNote.Lines`, a sub_field of this struct: what the note
takes back of the bill. `MishkaPay.list_credit_note_lines/4` answers them too. What the caller
gives, one of two kinds:

  * a line of the bill: `:invoice_line_id` (a `MishkaPay.Invoice.Lines` id, `il_...` at
    Stripe), with a `:quantity` of it to credit, or an `:amount` (a part of the line's amount);
  * a line of its own: a `:name` and a `:unit_amount` (the credit for one), with a `:quantity`
    (1 unless given).

What the provider fills in: `:id` (`cnli_...` at Stripe), `:type` (`:invoice_line` or
`:custom`) and `:amount`, the line's whole credit.

# `t`

```elixir
@type t() :: %MishkaPay.CreditNote{
  amount: Money.t() | nil,
  amount_tax: Money.t() | nil,
  created_at: DateTime.t() | nil,
  credit_amount: Money.t() | nil,
  customer_id: String.t() | nil,
  id: String.t() | nil,
  invoice_id: String.t() | nil,
  lines: [MishkaPay.CreditNote.Lines.t()] | nil,
  memo: String.t() | nil,
  metadata: map() | nil,
  number: String.t() | nil,
  out_of_band_amount: Money.t() | nil,
  pdf_url: String.t() | nil,
  provider: String.t(),
  reason:
    (:duplicate | :fraudulent | :order_change | :product_unsatisfactory) | nil,
  reference: String.t() | nil,
  refund_amount: Money.t() | nil,
  refund_ids: list() | nil,
  status: (:issued | :void) | nil,
  tenant: term() | nil,
  type: (:pre_payment | :post_payment | :mixed) | nil,
  voided_at: DateTime.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 |  |  | `validate(string)` |
| `:invoice_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:lines` | [`[MishkaPay.CreditNote.Lines.t()]`](`t:MishkaPay.CreditNote.Lines.t/0`) \| `nil` | no |  |  | `validate(list)` |
| `:reason` | `:duplicate` \| `:fraudulent` \| `:order_change` \| `:product_unsatisfactory` \| `nil` | no |  |  | `validate(enum=Atom[duplicate::fraudulent::order_change::product_unsatisfactory])`<br>validator `{MishkaPay.CreditNote, :reason}` |
| `:refund_amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:credit_amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:out_of_band_amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:memo` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=5000)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:number` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:status` | `:issued` \| `:void` \| `nil` | no |  |  | `validate(enum=Atom[issued::void])` |
| `:type` | `:pre_payment` \| `:post_payment` \| `:mixed` \| `nil` | no |  |  | `validate(enum=Atom[pre_payment::post_payment::mixed])` |
| `:amount_tax` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:refund_ids` | `list()` \| `nil` | no | `[]` |  | `validate(list)` |
| `:pdf_url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:voided_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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