Count tax, send invoices and issue credit notes
v0.0.1
Tax, bills and corrections are one job: charge the right amount, send it as a document and fix it without breaking the books. This guide turns on automatic tax with Stripe Tax, counts tax outside a checkout, sets rates by hand, makes a one-off invoice with invoice items, and issues a credit note on a finalized invoice. The calls work the same on every site, and a Mishka CMS site passes its own id as the tenant. PayPal supports none of them. See Capabilities by provider.
Before you begin
- Mishka Pay installed with a Stripe key. See Get Started.
- Stripe Tax turned on in the Dashboard with your head office and registrations, before
automatic_taxcounts anything. An account without it answersErrors.Rejectedwith code"tax_not_set_up". - A customer for invoices. See Save customers and cards, and open the billing portal.
Count tax at checkout
Set it on one checkout, or for the whole site with automatic_tax: true in the keys. A checkout's own choice wins.
MishkaPay.checkout(%{
# provider, items, URLs and reference as in a normal checkout
automatic_tax: true,
billing_address: :required,
tax_id_collection: true
})- Give each item a
tax_code, such as"txcd_10302000"for a digital book and"txcd_10103001"for SaaS. tax_behavioron a price or an item is:exclusive(tax is added on top) or:inclusive(the amount holds the tax). It can be set once on a price that had none. Otherwise make a new price.- An account with Stripe Tax on but no registration where the buyer lives counts a tax of zero.
- A checkout read back shows
:amount_totaland:amount_tax.
Set up Stripe Tax from code
MishkaPay.update_tax_settings(%{
provider: "stripe",
tenant: site.id,
head_office: %{
country: "NL",
line1: "Keizersgracht 1",
city: "Amsterdam",
postal_code: "1015 AA"
},
tax_behavior: :exclusive
})
{:ok, settings} =
MishkaPay.fetch_tax_settings("stripe", site.id)
settings.status
#=> :pending, until the missing fields are given
settings.missing_fields
MishkaPay.create_tax_registration(%{
provider: "stripe",
tenant: site.id,
country: "NL",
type: "standard"
})A US registration and Canada's "province_standard" need :state. Any other registration refuses one. A "standard" registration may name its :place_of_supply_scheme. A second registration of the same kind in a country is Errors.Rejected. Stripe never deletes a registration: expire_tax_registration/4 ends it.
Count tax outside a checkout
For a sale you charge yourself, ask Stripe for the tax first, charge the total, then record the sale in Stripe's tax reports.
{:ok, calc} =
MishkaPay.calculate_tax(%{
provider: "stripe",
tenant: site.id,
address: %{
country: "DE",
postal_code: "10115",
city: "Berlin",
line1: "Invalidenstr. 1"
},
items: [
%{
amount: %{amount: "100", currency: "EUR"},
quantity: 1,
tax_code: "txcd_10103001",
reference: "line-1"
}
]
})
calc.amount_total #=> the total to charge
{:ok, _tx} =
MishkaPay.record_tax("stripe", calc.id, "order-1001", site.id)A tax line's :amount is the whole line (unit price times quantity). The reference of record_tax/4 must be unique across all of Stripe's tax transactions, and a calculation can be recorded for 90 days.
Set a tax rate by hand
When you set the tax yourself, make a rate once and put its id on lines.
{:ok, rate} =
MishkaPay.create_tax_rate(%{
provider: "stripe",
tenant: site.id,
display_name: "VAT",
percentage: "21",
inclusive: false,
country: "NL"
})
MishkaPay.update_tax_rate(%{
provider: "stripe",
tenant: site.id,
id: old_rate.id,
active: false
})Use tax_rate_ids: [rate.id] on a checkout item, an invoice item or a draft bill. A rate never changes its percentage. Make a new one and archive the old one. Rates and automatic_tax do not go together on one checkout, and a catalog price or payment link takes no rate. Each is Errors.Invalid on :tax_rate_ids.
Make and send an invoice
An invoice bills a customer outside any subscription. Create the draft, finalize it, then send it or let Stripe charge the saved card.
{:ok, invoice} =
MishkaPay.create_invoice(%{
provider: "stripe",
tenant: site.id,
customer_id: customer.id,
collection: :send_invoice,
days_until_due: 14,
items: [
%{
name: "Design work",
amount: %{amount: "800", currency: "USD"},
quantity: 1
}
],
reference: "invoice-2026-17"
})
{:ok, invoice} =
MishkaPay.finalize_invoice("stripe", invoice.id, site.id)
{:ok, invoice} =
MishkaPay.send_invoice("stripe", invoice.id, site.id)- All items share one currency. A recurring price is refused, because a plan starts with a checkout.
collectionis:charge_automatically(the default) or:send_invoice.days_until_duegoes only with:send_invoice.- End a bill with
pay_invoice(p, id, tenant, out_of_band: true)(paid by other means),void_invoice/3,mark_invoice_uncollectible/3or, for a draft,delete_invoice/3. - A read bill has
:hosted_urland:pdf_urlfor the buyer. Read one withfetch_invoice/3, a customer's withlist_invoices("stripe", site.id, customer_id: customer.id). - A site with merchant of record on cannot send one-off bills, because Stripe sells as merchant of record only through checkouts and payment links.
Add an invoice item
An invoice item is a charge that waits for the customer's next bill, or goes on a draft one with invoice_id.
MishkaPay.create_invoice_item(%{
provider: "stripe",
tenant: site.id,
customer_id: customer.id,
name: "Extra seat, November",
amount: %{amount: "12", currency: "USD"},
reference: "seat-nov"
})
MishkaPay.list_invoice_items("stripe", site.id,
customer_id: customer.id,
pending: true
)The reference makes it charge once. delete_invoice_item/3 takes one back before its bill is finalized. An item on a finalized invoice cannot change or be deleted, and an item cannot move to another customer or bill.
Issue a credit note
A credit note takes back part or all of a finalized bill the tax-correct way. A draft cannot take one.
{:ok, preview} =
MishkaPay.preview_credit_note(%{
provider: "stripe",
tenant: site.id,
invoice_id: invoice.id,
amount: %{amount: "100", currency: "USD"},
reason: :order_change
})
MishkaPay.create_credit_note(%{
provider: "stripe",
tenant: site.id,
invoice_id: invoice.id,
amount: %{amount: "100", currency: "USD"},
reason: :order_change,
refund_amount: %{amount: "100", currency: "USD"},
reference: "cn-1"
}):amountcredits the bill as a whole.:linescredits lines of the bill by theiril_...id, or a line of its own.- On an open bill, the note lowers what is due. On a paid bill,
:refund_amountplus:credit_amountplus:out_of_band_amountmust equal the note. A bill paid by hand has no charge to refund, so use the other two. reasonis:duplicate,:fraudulent,:order_changeor:product_unsatisfactory.void_credit_note/3works only while the bill is still open.
Next steps
- Sell and manage subscriptions: invoices that a renewal makes.
- Refund, hold and capture a payment: money back without a credit note.
- Errors and telemetry: the tax error codes.