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:namewith an:amount(the price of one);:quantity(1 unless given),:tax_code,:tax_behaviorand:tax_rate_ids(the seller's ownMishkaPay.TaxRates on it) as on aMishkaPay.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
Functions
A sample %MishkaPay.Invoice.Item{} populated from defaults + type-based fallbacks.
Types
@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.
| 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) | ||
:customer_id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:invoice_id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:price_id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:name | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=500) | ||
:amount | Money.t() | nil | no | validator {MishkaPay.Money, :signed_field} | ||
:quantity | pos_integer() | nil | no | validate(integer, min_len=1) | ||
:tax_code | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=100) | ||
:tax_behavior | :inclusive | :exclusive | nil | no | validate(enum=Atom[inclusive::exclusive])<br>validator {MishkaPay.Price, :tax_behavior} | ||
:tax_rate_ids | list() | nil | no | sanitize(each=[trim]) validate(list, each=[string, not_empty]) | ||
:total | Money.t() | nil | no | validator {MishkaPay.Money, :signed_field} | ||
:period_start | DateTime.t() | nil | no | validate(struct) | ||
:period_end | DateTime.t() | nil | no | validate(struct) | ||
:reference | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=200) | ||
:created_at | DateTime.t() | nil | no | validate(struct) | ||
:metadata | map() | nil | no | %{} | validate(map)<br>validator {MishkaPay.Checkout, :metadata} |