A credit note: the tax-correct way to take back part or all of a finalized bill, instead of
changing it. Made with MishkaPay.create_credit_note/1 (try it first with
MishkaPay.preview_credit_note/1), read with MishkaPay.fetch_credit_note/3, listed with
MishkaPay.list_credit_notes/3 and MishkaPay.list_credit_note_lines/4, and ended with
MishkaPay.void_credit_note/3. A guarded_struct.
What the caller gives:
:provider,:tenant: which provider, with whose keys.:invoice_id: the finalized bill it credits (MishkaPay.Invoice).- What it credits, one of them: an
:amountof the whole bill, or:lines, each aMishkaPay.CreditNote.Lines(a line of the bill, or a line of its own). :reason::duplicate,:fraudulent,:order_changeor:product_unsatisfactory.- Where the money goes, on a paid bill:
:refund_amountback to the buyer's card,:credit_amountonto the customer's balance (taken off their next bills),:out_of_band_amountgiven back outside the provider. Together they make the note's amount. On an open bill the note lowers what is still due instead. :memo: text on the note the buyer sees.:reference: the caller's own id for it; it makes the idempotency key, so the same reference never credits twice, and it comes back on it.:metadata: extra pairs, string keys to string values.
Every amount is in the bill's currency.
What the provider fills in: :id (cn_... at Stripe), :number, :status (:issued or
:void), :type (:pre_payment when the bill was open, :post_payment when it was paid,
:mixed), :customer_id, :amount (all of it, tax included), :amount_tax, the :lines,
:refund_ids (the refunds it made), :pdf_url, :voided_at and :created_at. A preview
answers the same, from a note not made.
Lines
Each of :lines is a MishkaPay.CreditNote.Lines, a sub_field of this struct: what the note
takes back of the bill. MishkaPay.list_credit_note_lines/4 answers them too. What the caller
gives, one of two kinds:
- a line of the bill:
:invoice_line_id(aMishkaPay.Invoice.Linesid,il_...at Stripe), with a:quantityof it to credit, or an:amount(a part of the line's amount); - a line of its own: a
:nameand a:unit_amount(the credit for one), with a:quantity(1 unless given).
What the provider fills in: :id (cnli_... at Stripe), :type (:invoice_line or
:custom) and :amount, the line's whole credit.
Summary
Functions
A sample %MishkaPay.CreditNote{} populated from defaults + type-based fallbacks.
Types
@type t() :: %MishkaPay.CreditNote{ amount: Money.t() | nil, amount_tax: Money.t() | nil, created_at: DateTime.t() | nil, credit_amount: Money.t() | nil, customer_id: String.t() | nil, id: String.t() | nil, invoice_id: String.t() | nil, lines: [MishkaPay.CreditNote.Lines.t()] | nil, memo: String.t() | nil, metadata: map() | nil, number: String.t() | nil, out_of_band_amount: Money.t() | nil, pdf_url: String.t() | nil, provider: String.t(), reason: (:duplicate | :fraudulent | :order_change | :product_unsatisfactory) | nil, reference: String.t() | nil, refund_amount: Money.t() | nil, refund_ids: list() | nil, status: (:issued | :void) | nil, tenant: term() | nil, type: (:pre_payment | :post_payment | :mixed) | nil, voided_at: DateTime.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 | validate(string) | ||
:invoice_id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:customer_id | String.t() | nil | no | validate(string) | ||
:amount | Money.t() | nil | no | validator {MishkaPay.Money, :field} | ||
:lines | [MishkaPay.CreditNote.Lines.t()] | nil | no | validate(list) | ||
:reason | :duplicate | :fraudulent | :order_change | :product_unsatisfactory | nil | no | validate(enum=Atom[duplicate::fraudulent::order_change::product_unsatisfactory])<br>validator {MishkaPay.CreditNote, :reason} | ||
:refund_amount | Money.t() | nil | no | validator {MishkaPay.Money, :field} | ||
:credit_amount | Money.t() | nil | no | validator {MishkaPay.Money, :field} | ||
:out_of_band_amount | Money.t() | nil | no | validator {MishkaPay.Money, :field} | ||
:memo | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=5000) | ||
:reference | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=200) | ||
:metadata | map() | nil | no | %{} | validate(map)<br>validator {MishkaPay.Checkout, :metadata} | |
:number | String.t() | nil | no | validate(string) | ||
:status | :issued | :void | nil | no | validate(enum=Atom[issued::void]) | ||
:type | :pre_payment | :post_payment | :mixed | nil | no | validate(enum=Atom[pre_payment::post_payment::mixed]) | ||
:amount_tax | Money.t() | nil | no | validator {MishkaPay.Money, :field} | ||
:refund_ids | list() | nil | no | [] | validate(list) | |
:pdf_url | String.t() | nil | no | validate(string) | ||
:voided_at | DateTime.t() | nil | no | validate(struct) | ||
:created_at | DateTime.t() | nil | no | validate(struct) |