Skip to main content

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.
A credit note uses the same endpoints, the same JSON fields and the same UBL BIS Billing 3.0 rules as an invoice. If you did not send an invoice before, read Create e-invoices first. For a credit note that your company issues as the buyer, see Self-billing credit notes.

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 invoice INV-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
This credit note has positive amounts. Replace the vendor fields with the data of your company. The API rejects a document if the Peppol ID of the vendor is not one of the 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.
To validate the credit note, send the same body to 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 POST /api/documents/.
The API returns 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)
Keep the id. You use it in the next step.
2

Send the credit note

Call 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.
The API returns 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 own invoice_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, add payment_term and payment_details.

Allowances and charges

A credit note accepts the same allowances 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

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.
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 and tax categories of the original invoice, also if the rates changed after the invoice date.
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

  1. Make sure that the Peppol ID of the customer is correct. See Look up Peppol participants.
  2. Get the state of the document with GET /api/documents/{document_id}.
  3. Get the delivery history with GET /api/documents/{document_id}/timeline. See Document lifecycle and delivery tracking.
  4. Examine the webhook events for the document.
For all status codes and error formats, see Errors and troubleshooting.

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