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

A tax rate the seller sets by hand (`txr_...` at Stripe), such as 19% German VAT: the provider
adds it to the lines it is put on, without counting the tax itself as Stripe Tax does. A
guarded_struct, made with `MishkaPay.create_tax_rate/1`, read with `MishkaPay.fetch_tax_rate/3`
and `MishkaPay.list_tax_rates/3`, and changed with `MishkaPay.update_tax_rate/1`.

A rate goes on a line by its id: `:tax_rate_ids` of a checkout's item (`MishkaPay.Price`), of an
invoice item (`MishkaPay.Invoice.Item`), or of a whole draft bill (`MishkaPay.Invoice.Draft`).

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:display_name` (required): what the buyer reads on the bill, such as `"VAT"`.
  * `:percentage` (required): from 0 to 100, an integer, a `Decimal` or a number in a string
    (`"7.25"`); never a float.
  * `:inclusive` (required): `true` when the line's amount already holds the tax (as in much of
    Europe), `false` when the tax is added on top (as in the US).
  * `:country` (two letters), `:state` (ISO 3166-2 without the country, such as `"NY"`),
    `:jurisdiction` (a label for the tax reports and the bill) and `:tax_type`, in the
    provider's words (`"vat"`, `"sales_tax"`, `"gst"`...).
  * `:description`: for the seller only; the buyer never sees it.
  * `:active`: `false` archives the rate: no new line takes it, and the lines that have it keep
    it. A provider never deletes a rate.
  * `:reference`: the caller's own id for it; it makes the idempotency key, so the same
    reference never makes two rates, and it comes back on it.
  * `:metadata`: extra pairs, string keys to string values.

What the provider fills in: `:id`, `:effective_percentage` (what is charged now, where the rate
depends on the place) and `:created_at`.

A change (`:id` given) names only what it changes; a rate's `:percentage` and `:inclusive` never
change: make a new rate and archive the old one.

# `t`

```elixir
@type t() :: %MishkaPay.TaxRate{
  active: boolean() | nil,
  country: String.t() | nil,
  created_at: DateTime.t() | nil,
  description: String.t() | nil,
  display_name: String.t() | nil,
  effective_percentage: Decimal.t() | nil,
  id: String.t() | nil,
  inclusive: boolean() | nil,
  jurisdiction: String.t() | nil,
  metadata: map() | nil,
  percentage: Decimal.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  state: String.t() | nil,
  tax_type: String.t() | nil,
  tenant: term() | 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)` |
| `:display_name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=50)` |
| `:percentage` | `Decimal.t()` \| `nil` | no |  |  | validator `{MishkaPay.TaxRate, :percentage}` |
| `:effective_percentage` | `Decimal.t()` \| `nil` | no |  |  | validator `{MishkaPay.TaxRate, :percentage}` |
| `:inclusive` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:active` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:country` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, upcase) validate(string, regex=^[A-Z]{2}$)` |
| `:state` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, upcase) validate(string, max_len=10)` |
| `:jurisdiction` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=50)` |
| `:tax_type` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, not_empty, max_len=50, regex=^[a-z][a-z_]*$)` |
| `:description` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, 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}` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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