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_tax counts anything. An account without it answers Errors.Rejected with 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.

elixir
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_behavior on 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_total and :amount_tax.

Set up Stripe Tax from code

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

elixir
{: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.

elixir
{: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.

elixir
{: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.
  • collection is :charge_automatically (the default) or :send_invoice. days_until_due goes 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/3 or, for a draft, delete_invoice/3.
  • A read bill has :hosted_url and :pdf_url for the buyer. Read one with fetch_invoice/3, a customer's with list_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.

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

elixir
{: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"
})
  • :amount credits the bill as a whole. :lines credits lines of the bill by their il_... id, or a line of its own.
  • On an open bill, the note lowers what is due. On a paid bill, :refund_amount plus :credit_amount plus :out_of_band_amount must equal the note. A bill paid by hand has no charge to refund, so use the other two.
  • reason is :duplicate, :fraudulent, :order_change or :product_unsatisfactory.
  • void_credit_note/3 works only while the bill is still open.

Next steps