MishkaPay.TaxCalculation (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

@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.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:items[MishkaPay.TaxCalculation.Items.t()] | nilnovalidate(not_nil_value, list)
:addressMishkaPay.Address.t() | nilno
:customer_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:address_source:billing | :shipping | nilno:billingvalidate(not_nil_value, enum=Atom[billing::shipping])<br>validator {MishkaPay.TaxCalculation, :address_source}
:shippingMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:idString.t() | nilnovalidate(string)
:amount_totalMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:tax_amount_exclusiveMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:tax_amount_inclusiveMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:expires_atDateTime.t() | nilnovalidate(struct)
:transactionMishkaPay.TaxCalculation.Transaction.t() | nilnoA 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.

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)