MishkaPay.TaxRate (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

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

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnosanitize(trim) validate(string, not_empty)
:display_nameString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=50)
:percentageDecimal.t() | nilnovalidator {MishkaPay.TaxRate, :percentage}
:effective_percentageDecimal.t() | nilnovalidator {MishkaPay.TaxRate, :percentage}
:inclusiveboolean() | nilnovalidate(boolean)
:activeboolean() | nilnovalidate(boolean)
:countryString.t() | nilnosanitize(trim, upcase) validate(string, regex=^[A-Z]{2}$)
:stateString.t() | nilnosanitize(trim, upcase) validate(string, max_len=10)
:jurisdictionString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=50)
:tax_typeString.t() | nilnosanitize(trim, downcase) validate(string, not_empty, max_len=50, regex=^[a-z][a-z_]*$)
:descriptionString.t() | nilnosanitize(trim) validate(string, max_len=5000)
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:created_atDateTime.t() | nilnovalidate(struct)

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)