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

The tax on a sale made outside the provider's checkout, counted by the provider (Stripe Tax):
a site that charges with its own form, or sells on an invoice it makes itself, asks
`MishkaPay.calculate_tax/1` what tax to add, shows it, charges the total, then reports the sale
with `MishkaPay.record_tax/4`. A guarded_struct.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:items`: one or more `MishkaPay.TaxCalculation.Items`, all in one currency, at most 100.
  * `:address`: where the buyer is, a `MishkaPay.Address` (its `:country`, and its
    `:postal_code` in the US), with `:address_source` `:billing` (the default) or `:shipping`;
    or `:customer_id`, a provider customer whose saved address and tax ids are used. One or the
    other is needed; given both, the address wins.
  * `:shipping`: what shipping costs, as `Money` in the items' currency; the provider counts its
    tax too.

What the provider fills in:

  * `:id`: the calculation's id (`taxcalc_...` at Stripe), which `MishkaPay.record_tax/4`
    takes.
  * `:amount_total`: what the buyer pays in all, tax and shipping included.
  * `:tax_amount_exclusive`: the tax added on top of the amounts; `:tax_amount_inclusive`: the
    tax already inside amounts given with `tax_behavior: :inclusive`.
  * `:items`: each line again, with its `:amount_tax`.
  * `:expires_at`: after this the calculation can no longer be recorded.

A provider counts tax only where the account is set up for it (Stripe Tax: an origin address
and the places it is registered); elsewhere the tax is zero. An account that never turned the
tax service on is refused with `MishkaPay.Errors.Rejected`, code `"tax_not_set_up"`.

## Items

Each of `:items` is a `MishkaPay.TaxCalculation.Items`, a sub_field of this struct: one line of
the sale, what is sold, for how much in all, and the tax the provider counted on it.

What the caller gives:

  * `:reference`: the caller's own name for the line, such as a SKU or an order line id; one
    per line, unique within the calculation. It comes back on the line and in the provider's
    tax reports.
  * `:amount`: what the whole line costs, the unit price times `:quantity`, as `Money` (or
    `%{amount: "30.00", currency: "EUR"}`).
  * `:quantity`: how many, 1 by default.
  * `:tax_code`: the provider's tax category of what is sold (Stripe's `"txcd_10302000"` for
    an e-book); the provider's default category when left out.
  * `:tax_behavior`: `:exclusive` (the default: tax is added on top) or `:inclusive` (the
    amount already holds it).
  * `:product_id`: a catalog product whose tax category is used when `:tax_code` is left out.

What the provider fills in: `:id` and `:amount_tax`, the tax on the line.

# `t`

```elixir
@type t() :: %MishkaPay.TaxCalculation{
  address: MishkaPay.Address.t() | nil,
  address_source: (:billing | :shipping) | nil,
  amount_total: Money.t() | nil,
  customer_id: String.t() | nil,
  expires_at: DateTime.t() | nil,
  id: String.t() | nil,
  items: [MishkaPay.TaxCalculation.Items.t()] | nil,
  provider: String.t(),
  shipping: Money.t() | nil,
  tax_amount_exclusive: Money.t() | nil,
  tax_amount_inclusive: Money.t() | nil,
  tenant: term() | nil,
  transaction: MishkaPay.TaxCalculation.Transaction.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 |  |  |  |
| `:items` | [`[MishkaPay.TaxCalculation.Items.t()]`](`t:MishkaPay.TaxCalculation.Items.t/0`) \| `nil` | no |  |  | `validate(not_nil_value, list)` |
| `:address` | [`MishkaPay.Address.t()`](`t:MishkaPay.Address.t/0`) \| `nil` | no |  |  |  |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:address_source` | `:billing` \| `:shipping` \| `nil` | no | `:billing` |  | `validate(not_nil_value, enum=Atom[billing::shipping])`<br>validator `{MishkaPay.TaxCalculation, :address_source}` |
| `:shipping` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:amount_total` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:tax_amount_exclusive` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:tax_amount_inclusive` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:expires_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:transaction` | [`MishkaPay.TaxCalculation.Transaction.t()`](`t:MishkaPay.TaxCalculation.Transaction.t/0`) \| `nil` | no |  | A sale reported to the provider's tax records from a `MishkaPay.TaxCalculation`, with `MishkaPay.record_tax/4`: the provider then counts its tax in the site's tax reports and filings. A guarded_struct the provider fills in. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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