Guide

Cancellations, corrections and credit notes: 384 or 381?

Three transactions that German business language all calls “Gutschrift” — and three type codes, one of which (381) the UBL Invoice syntax rejects. Which code belongs to which transaction, what the JSON looks like, and what the validator says about it.

Updated on September 22, 2026

Which three things are called “Gutschrift” in German?

In German invoicing the word “Gutschrift” covers three different transactions, and EN 16931 gives each one its own type code (BT-3, code list UNTDID 1001). Picking the code by the word on the document instead of by the transaction quickly lands on the wrong one — and in a UBL Invoice on a rejection.

The third row is the trap: in German VAT law a “Gutschrift” is not a refund but an invoice the customer issues on behalf of the supplier. A cancellation is, for VAT purposes, an invoice correction — and therefore a 384 in EN 16931, not a 381 and certainly not a 389. The type code carries the meaning unambiguously; the word on the PDF does not.

How do I cancel an invoice?

KoSIT answered this in issue #58 of the XRechnung validator repository. The position of KoSIT staff there: type 381 “Credit Note” is meant for commercial credit notes, not for invoice corrections. A cancellation is a 100 % invoice correction and is issued as a 384 “Corrected Invoice” with the signs of the quantities (BT-129) and amounts reversed. That negative quantities and a negative amount due are permitted in a UBL Invoice is shown by the official XRechnung 3.0.2 test suite: it contains instances with a negative InvoicedQuantity and one with a negative PayableAmount that the validator must accept — a fully negative cancellation as a 384 is not among them, though; its only 384 is a replacement invoice with positive quantities.

In a normbill request, a complete cancellation looks like this:

{
  "format": "xrechnung-3.0",
  "invoice": {
    "number": "RE-2026-0142-S",
    "issue_date": "2026-09-22",
    "type_code": "384",
    "preceding_invoice": "RE-2026-0142",
    "buyer_reference": "04011000-1234512345-06",
    "seller": {
      "name": "Muster Lieferant GmbH", "vat_id": "DE123456789",
      "address": { "country": "DE", "city": "Berlin", "postal_code": "10115" },
      "contact": { "name": "Billing", "phone": "+49 30 1234567",
                   "email": "billing@lieferant.example" }
    },
    "buyer": {
      "name": "Beispiel Kunde AG",
      "address": { "country": "DE", "city": "Hamburg", "postal_code": "20095" },
      "contact": { "email": "ap@kunde.example" }
    },
    "payment": { "iban": "DE89370400440532013000" },
    "lines": [
      { "name": "Beratungsleistung", "qty": -10, "unit_price": 100, "vat": 19 }
    ]
  }
}

Three things here are deliberate:

• The sign goes into the quantity, not the price. unit_price must be zero or greater (BR-27); a negative price never reaches the validator — the request schema already rejects it with a 400 and the BR-27 hint. With qty: -10 normbill computes the totals itself: net −1,000.00, VAT −190.00, gross −1,190.00.
• preceding_invoice names the cancelled invoice. If the field is missing on a 384, the tier-1 check reports BR-DE-26 as a warning at path: "invoice.preceding_invoice" — the document stays valid, but the recipient cannot match the cancellation to any invoice. Always set it.
• The number is new. A cancellation is its own document with its own invoice number (BT-1); the old number appears only in BT-25.

Whether a partial correction is issued as a delta (only the reversed lines, with negative quantities) or as a complete replacement invoice is not prescribed by XRechnung — it is an agreement with the recipient; both are a 384 with preceding_invoice. In both cases the sign belongs in the quantity, never in the price. A replacement invoice carries positive quantities and a positive amount due — and then, like any invoice, needs a due_date or payment.terms (BR-CO-25).

When is 381 right — and why not in a UBL Invoice?

A 381 is the commercial credit note: a bonus, a goodwill refund, a retroactive discount — a credit that does not correct a specific invoice. In the UBL binding of EN 16931, however, code list UNTDID 1001 lists 381 only for the CreditNote document type, not for Invoice. CII has no such split: the single root element CrossIndustryInvoice carries the type code in its TypeCode element, and 381 is valid there.

That is why normbill emits 381 in the CII syntaxes (xrechnung-cii-3.0, zugferd-2.x, facturx-1.0). In the UBL formats (xrechnung-3.0, peppol-bis-3.0) the tier-1 pre-flight reports a 381 as BR-CL-01 at path: "invoice.type_code" — the response is a 422 and no XML is returned; the JSON playground on the home page shows the same finding. Two ways out:

• Switch the format to xrechnung-cii-3.0. It is the second official XRechnung syntax; normbill validates it against the KoSIT validator just like the UBL variant.
• Express it as a 384 if the credit in fact corrects an invoice — then 384 with preceding_invoice is the right code anyway.

A UBL CreditNote document (its own root element, its own KoSIT scenario “EN16931 XRechnung (UBL CreditNote)” in the pinned configuration) is not something normbill emits today; in UBL, /v1/invoices/parse also accepts Invoice documents only.

Sign on a 381: XRechnung currently has no rule on whether a commercial credit note carries positive or negative amounts. In the same thread, a CEN editor announced on 2 January 2025 that the upcoming revision of EN 16931-1 will no longer allow negative credit-note totals. Positive quantities on a 381 are therefore the future-proof shape — the document says through its code that it is a credit. Mind BR-CO-25 while doing so: a positive amount due requires a due_date or payment.terms (e.g. “offset against the next invoice”).

Which rules check the type code and the sign?

Where next?

Validator · Playground · Docs · How to read KoSIT errors

Deutsche Version →