Overview
A credit note decreases or cancels an invoice that you issued. Typical causes are:- Refund - the customer returns goods or cancels a service.
- Correction - the invoice had a wrong price, quantity or amount.
- Discount after the invoice - you give a price adjustment for an invoice that is already sent.
- Cancellation - the invoice was issued in error.
Differences from an invoice
The JSON document has no field for the number of the original invoice. Write the number of the original invoice in
note. The purchase_order field keeps its meaning: it is the order number of the customer, and the API writes it to the order reference and the buyer reference of the UBL document.Example credit note
The original invoiceINV-2026-001 has 10 units at €100.00. The customer returns 2 units. The credit note is for €242.00 (2 × €100.00 plus 21% VAT).
Credit note
peppol_ids of your company.
Save this payload as credit-note.json. The code samples on this page read that file.
Create and send a credit note
Validation is not a separate mandatory call.
POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.POST /api/validate/json. See Validation during development.
Develop and test with a sandbox company. A sandbox company runs in test mode: the API sends each document as UBL XML to the contact email address of the company, and nothing goes to the Peppol network. The API host and the endpoints are the same as for a production company. See Test mode and sandbox companies.
1
Create the credit note
Send the payload to The API returns Keep the
POST /api/documents/.201 and the document in the DRAFT state. The response has all fields of the document. This example shows a selection. Amounts in the response are strings.Response (201)
id. You use it in the next step.2
Send the credit note
Call The API returns
POST /api/documents/{document_id}/send with the id from the create response. The call is the same as for an invoice. Replace the sender Peppol ID in the query parameters with the Peppol ID of your company.200 and the document. The state is no longer DRAFT.Response (200)
3
Monitor the delivery
The document goes to
SENT or to FAILED. Use webhooks (document.sent and document.sent.failed) or read the timeline of the document. See Document lifecycle and delivery tracking.Document states
A credit note has the same states as an invoice.
You can send a document only when it is in the
DRAFT or FAILED state. For the transitions, the retry behaviour and the webhook events of each state, see Document lifecycle and delivery tracking.
Variants of the example
Each block below shows only the fields that are different from the example credit note. All other fields stay the same. Give each credit note its owninvoice_id.
Full credit
To cancel the invoice fully, include each line of the original invoice with the same quantity and the same price.Price correction
To correct a price, credit the difference. In this example the invoice price was €10.00 too high for each unit. The credit is €121.00 (10 × €10.00 plus 21% VAT).More than one line
In this example the customer returns 5 units of the first product and 3 units of the second product. The credit is €786.50.Service cancellation
In this example you credit one day of a service that the customer did not use.Refund details
To tell the customer how you pay the refund, addpayment_term and payment_details.
Allowances and charges
A credit note accepts the sameallowances and charges as an invoice, at document level and at line level. See Advanced invoicing for the fields and Invoice totals and calculations for the calculation of the totals.
Good practice
Name the original invoice
Name the original invoice
Write the number of the original invoice and the reason for the credit in
note. The customer can then match the credit note with the invoice.Use the descriptions of the original invoice
Use the descriptions of the original invoice
If you credit specific lines of the original invoice, use the same descriptions and unit prices. Add the reason to the description.
Use the tax rates of the original invoice
Use the tax rates of the original invoice
Use the tax rates and tax categories of the original invoice, also if the rates changed after the invoice date.
Use positive amounts
Use positive amounts
Give the credited quantities and amounts as positive values. The document type
CREDIT_NOTE tells the receiver that the document decreases the amount due.Troubleshooting
The API rejects the credit note
POST /api/documents/ returns 406 if the payload does not pass the validation rules or if the Peppol ID of the vendor is not a Peppol ID of your company. It returns 422 if a field has a wrong type or format. No document is created. Send the body to POST /api/validate/json to see the rule failures, and see Create document errors.
The total of the credit note is more than the total of the invoice
The API does not compare a credit note with the original invoice. A higher total can be correct, for example when you also credit return shipping costs. Make sure that your accounting system and that of the customer accept this.The customer did not receive the credit note
- Make sure that the Peppol ID of the customer is correct. See Look up Peppol participants.
- Get the state of the document with
GET /api/documents/{document_id}. - Get the delivery history with
GET /api/documents/{document_id}/timeline. See Document lifecycle and delivery tracking. - Examine the webhook events for the document.
Next Steps
Document lifecycle and delivery tracking
Follow the states and the delivery of a credit note
Self-billing and debit notes
Issue credit notes as the buyer, and debit notes
Advanced invoicing
Add allowances and charges
Errors and troubleshooting
Find the cause of a rejected or failed document