Credit notes
A credit note reduces what a customer owes. It is the answer to "we billed this wrong", and it is the only answer, 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_code is required, and it is not decoration. It is the field finance
groups by when asking why revenue was given back.
The structured values are VOID, REFUND, PROMOTIONAL_CREDIT,
CANCELLATION, WITHDRAWAL, DOWNGRADE, ITEM_REMOVAL, OVERPAYMENT,
BILLING_ERROR, GOODWILL and OTHER.
reason is required too: free text, shown on the document the customer reads.
The code is for you; the text is for them.
OTHER is a smell, not a default
If most of your credit notes are OTHER, nobody can answer why money is being
returned. Pick the code that is true, and reserve OTHER for the genuinely
unusual.
Issued, then applied
A credit note moves through draft → issued → partially_applied →
applied, or void.
Issuing finalises the document, exactly as with an invoice. Applying is separate: it attaches the credit to one or more invoices and reduces their balances. A note can be issued and sit unapplied, which is what you want when the credit is meant for the customer's next bill rather than this one.
Create one in the dashboard
-
Start from the invoice
Open the invoice being corrected. Creating from the invoice carries its customer, currency and lines across, which is far less error-prone than starting blank.
-
Choose what to credit
Credit whole lines or partial amounts. Each line carries its own quantity, unit price and tax rate, so tax is reversed correctly rather than estimated.
-
Give the reason
Pick the structured reason, then write the sentence the customer will read.
-
Issue, then apply
Issuing produces the document. Applying reduces the invoice balance. They are two steps because you do not always want them in the same moment.
Create one over the API
customer_id, currency, reason_code, reason and at least one line are
required. Each line needs description, line_type, quantity, unit_price
and tax_rate.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Status | draft, issued, partially_applied, applied, void |
| Reason dropdown | reason_code, structured |
| the sentence on the document | reason, free text |
| Issue | POST /credit-notes/{id}/issue |
| Apply to invoice | POST /credit-notes/{id}/apply |
| download | GET /credit-notes/{id}/pdf |
Where credit notes go next
- The invoice balance drops when the note is applied, and the invoice can
reach
paidwithout more money arriving. - Refunds are different. A credit note reduces what is owed; a refund returns money already taken.
- Unapplied credit stays available for a later invoice.
Next step
Continue to Dunning for what happens when an invoice is not paid at all.
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 |