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 moreMishkaPay.TaxCalculation.Items, all in one currency, at most 100.:address: where the buyer is, aMishkaPay.Address(its:country, and its:postal_codein 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, asMoneyin the items' currency; the provider counts its tax too.
What the provider fills in:
:id: the calculation's id (taxcalc_...at Stripe), whichMishkaPay.record_tax/4takes.: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 withtax_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, asMoney(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_codeis left out.
What the provider fills in: :id and :amount_tax, the tax on the line.
Summary
Functions
A sample %MishkaPay.TaxCalculation{} populated from defaults + type-based fallbacks.
Types
@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()] | nil | no | validate(not_nil_value, list) | ||
:address | MishkaPay.Address.t() | 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() | 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. |