Copy page

When it goes sideways

Credit notes

A credit note reduces what a customer owes. It is how you correct an invoice that billed the wrong amount, and it is the only way, because a finalised invoice is immutable.

That immutability is not a limitation to work around. An issued invoice is a legal record, and correcting it by editing would destroy the audit trail that makes it one. A credit note leaves both documents standing: the original bill, and the correction, each with its own number and its own reason.

✕

Say why, reportably

reason is a closed set, and it is not decoration. It is persisted on the crediting document (several jurisdictions require the why on it) and it is the field finance groups by when asking why revenue was given back.

On POST /v1/credit-notes the values are REFUND, PROMOTIONAL_CREDIT, CANCELLATION, WITHDRAWAL, DOWNGRADE, ITEM_REMOVAL, OVERPAYMENT, BILLING_ERROR, GOODWILL and OTHER. Reversing a whole invoice (POST /v1/invoices/{id}/void) also accepts VOID. Omitting reason means OTHER.

A correction names what comes back

A credit note always corrects one issued document, named by original_document_id. You do not retype lines, prices or tax rates. You name the atoms of the original (its priced facts, one per product, key and segment, from GET /v1/invoices/{id}/atoms) and how much of each comes back:

• reversals[]: {atom_id, quantity}, the quantity a positive magnitude. The reversing money is the original's own money taken back proportionally, with its tax rate and FX pin, so tax is reversed exactly rather than re-estimated.
• new_entries[] (optional): corrected amounts that replace what was reversed.
• policy (optional): separate or single. Read only where the jurisdiction's law admits both; everywhere else the law decides.

What comes out is the jurisdiction's shape: under a separate-document law a credit note plus, where you stated corrected amounts, a replacement invoice; under a single-document law one corrective carrying both. The response names the original, the correction, the replacement where there is one, the policy that was applied and whether the original was reversed in full (original_reversed).

An empty reversals list with new_entries is a goodwill credit. To take the whole document back, reverse it instead with POST /v1/invoices/{id}/void, which mints the credit note for you.

Issued at once, spent at once

A correction is issued as it is created: it takes its number from the credit-note series in the same transaction. There is nothing left on the note to apply by hand. What the original still owes is taken off it, and what is left (money the customer had already paid) goes to the customer's wallet in the document's currency, as a ledger entry naming the credit note (credit_destination = wallet), which the wallet spends on their next invoice. A refund through the gateway (credit_destination = payment_method) goes back over the rail that took it instead; see Payments.

A credit note is an invoice in EN 16931's sense: it is an invoice resource with kind credit_note (or corrective under a single-document law), and it uses the same statuses. POST /v1/credit-notes/{id}/issue finalises a crediting document that is still a draft; POST /v1/credit-notes/{id}/void discards a draft. An issued one cannot be voided in place: the way back is to reverse it.

Correcting twice with the same request returns the first correction rather than minting a second.

Create one in the dashboard

Over the API, this is POST /v1/credit-notes; see Create one over the API.

Create one over the API

Read the original's atoms first, then name the ones that come back:

original_document_id and reversals are required. The answer is 201 with the correction.

Dashboard and API names

In the dashboard	In the API
Reason dropdown	reason, a closed set
the lines you credit	reversals[]: atom_id and quantity
corrected amounts	new_entries[]
Issue (a draft)	POST /credit-notes/{id}/issue
where the credit went	GET /credit-notes/{id}/applications
download	GET /credit-notes/{id}/pdf, GET /credit-notes/{id}/xrechnung

Where credit notes go next

1. The invoice balance drops at once, and the invoice can reach paid without more money arriving.
2. Refunds are different. A credit note reduces what is owed; a refund returns money already taken, and writes its own credit note.
3. Money already paid goes to the wallet and is spent on the customer's next invoice.
4. invoice.corrected is the webhook event for a corrected document.

Reference

Topic	When you need it
Invoices	Why a finalised invoice cannot be edited
Payments	Refunds, which return money rather than reduce a bill
Taxes	How tax is reversed on a credited line
Credit notes API	Every field, plus applications and PDF