MishkaPay.Invoice.Item (Mishka Pay v0.0.1)

Copy Markdown View Source

One charge for a customer kept on its own, outside MishkaPay.create_invoice/1: a setup fee, an extra seat, a late fee. Left off any bill it waits (pending) and goes on the customer's next bill, a subscription's renewal or a one-off bill; given :invoice_id it goes on that draft bill. Made with MishkaPay.create_invoice_item/1, changed with MishkaPay.update_invoice_item/1, listed with MishkaPay.list_invoice_items/3 and removed with MishkaPay.delete_invoice_item/3. A guarded_struct.

What the caller gives:

  • :provider, :tenant: which provider, with whose keys.
  • :customer_id: whose bill it goes on.
  • :invoice_id: a draft bill to put it on; left out, it waits for the customer's next bill.
  • What it charges: a catalog price by :price_id, or a :name with an :amount (the price of one); :quantity (1 unless given), :tax_code, :tax_behavior and :tax_rate_ids (the seller's own MishkaPay.TaxRates on it) as on a MishkaPay.Price.
  • :reference: the caller's own id for it; it makes the idempotency key, so the same reference never charges twice, and it comes back on it.
  • :metadata: extra pairs, string keys to string values.

What the provider fills in: :id (ii_... at Stripe), :total (the amount times the quantity; below zero for a credit), :period_start and :period_end, :created_at.

A change (:id given) names only what it changes: :name, :amount (in the item's own currency), :quantity, :price_id, the tax fields, :metadata. An item stays on its customer and bill; once its bill is finalized it cannot change or go.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

@type t() :: %MishkaPay.Invoice.Item{
  amount: Money.t() | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  id: String.t() | nil,
  invoice_id: String.t() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  period_end: DateTime.t() | nil,
  period_start: DateTime.t() | nil,
  price_id: String.t() | nil,
  provider: String.t(),
  quantity: pos_integer() | nil,
  reference: String.t() | nil,
  tax_behavior: (:inclusive | :exclusive) | nil,
  tax_code: String.t() | nil,
  tax_rate_ids: list() | nil,
  tenant: term() | nil,
  total: Money.t() | 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)
:customer_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:invoice_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:price_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:nameString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=500)
:amountMoney.t() | nilnovalidator {MishkaPay.Money, :signed_field}
:quantitypos_integer() | nilnovalidate(integer, min_len=1)
:tax_codeString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=100)
:tax_behavior:inclusive | :exclusive | nilnovalidate(enum=Atom[inclusive::exclusive])<br>validator {MishkaPay.Price, :tax_behavior}
:tax_rate_idslist() | nilnosanitize(each=[trim]) validate(list, each=[string, not_empty])
:totalMoney.t() | nilnovalidator {MishkaPay.Money, :signed_field}
:period_startDateTime.t() | nilnovalidate(struct)
:period_endDateTime.t() | nilnovalidate(struct)
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:created_atDateTime.t() | nilnovalidate(struct)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)