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, aDecimalor a number in a string ("7.25"); never a float.:inclusive(required):truewhen the line's amount already holds the tax (as in much of Europe),falsewhen 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:falsearchives 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.
Summary
Functions
A sample %MishkaPay.TaxRate{} populated from defaults + type-based fallbacks.
Types
@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) |