Attestwire › Rule reference › BR-CL-08

BR-CL-08 An invoice note subject code must come from UNCL 4451

noun · EN 16931 · fatal · BT-21

Your invoice was refused because the subject code on an invoice note is not in the UNCL 4451 code list. The code is optional: either use a code from the list, such as AAI for general information, or leave it out and keep a plain note. In the standard the field is BT-21, and BR-CL-08 is the rule that checks it.

Business term

BT-21 — Invoice note subject code

Severity

fatal

Applies to

All profiles

The fix

Set noteSubjectCode to a three-letter code from UNCL 4451, for example "AAI", or leave it unset: a note without a subject code is perfectly valid.

What the rule requires

The invoice note subject code (BT-21) tells a receiver what kind of note follows. When it is present, it must be a three-letter qualifier from the UN/CEFACT code list UNCL 4451. Common ones: AAI general information, REG regulatory information, ABL governing law, TXD tax declaration, PMT payment information, ACB additional information.

UBL, one of the two XML formats an e-invoice can be written in, has no element for BT-21. The binding puts the code in front of the note text, between hashes: #AAI#Leistungszeitraum Juli 2026. A validator reads it back out of that string, so a note that happens to begin with a hash-wrapped word is read as a subject code.

In this library the fields are note and noteSubjectCode.

Invoiced note subject code shall be coded using UNCL4451

A passing value

"note": "Leistungszeitraum Juli 2026", "noteSubjectCode": "AAI"

Why it exists

A coded subject lets a receiving system act on a note without reading it: file a legal remark as a legal remark, send a payment remark to accounts payable. That only works when every sender uses the same list, which is why the code, when present, has to come from UNCL 4451.

What the library returns

The full error returned by @attestwire/en16931. It includes the rule ID, affected field and suggested correction. Developers can use this object in their application:

{
  "rule": "BR-CL-08",
  "field": "BT-21",
  "severity": "fatal",
  "message": "The invoice note subject code (BT-21) is \"ZZ9\", which is not in UNCL 4451 (383 codes). UBL has no element for BT-21 at all: EN 16931's binding prefixes the code onto the note itself, so this library writes cbc:Note as \"#ZZ9#\" followed by your note text, and the validator parses it back out of that string.",
  "fix": "Set noteSubjectCode to a three-letter UNCL 4451 qualifier — \"AAI\" general information, \"REG\" regulatory information, \"ABL\" governing law, \"TXD\" tax declaration, \"PMT\" payment information, \"ACB\" additional information. Leave it unset if the note needs no subject; a plain note is perfectly valid.",
  "example": "\"note\": \"Leistungszeitraum Juli 2026\", \"noteSubjectCode\": \"AAI\"",
  "xpath": "/ubl:Invoice/cbc:Note",
  "docsUrl": "https://attestwire.com/rules/BR-CL-08"
}

xpath is always a UBL path. On a CII invoice, look for the matching CII field instead.

How our check differs

See also: BR-CL-01 — the code list rule for the invoice type code.