UBL XML Credit Note Format

When a recipient accepts UBL_CREDIT_NOTE, an owner device generates a UBL 2.1 CreditNote alongside the CHEQI JSON representation. Both documents describe the same definitive merchant values and share the same document UUID.

The root namespace is:

urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2

The document also declares the standard UBL Common Aggregate Components (cac) and Common Basic Components (cbc) namespaces.

Generated elements

Element	Present	Source
`cbc:UBLVersionID`	Always	Constant `2.1`.
`cbc:ID`	Always	`documentNumber`.
`cbc:UUID`	Always	Generated `receiptUuid`, shared with CHEQI JSON.
`cbc:IssueDate`	Always	Date portion of `issueDate`.
`cbc:IssueTime`	Always	Time portion of `issueDate`.
`cbc:CreditNoteTypeCode`	Always	Code `381` using the UN/ECE 1001 subset.
`cbc:Note`	Optional	Issuer's configured company receipt text. The legacy request `note` is ignored.
`cbc:DocumentCurrencyCode`	Always	`currency`, identified as ISO 4217 alpha.
`cac:OriginatorDocumentReference/cbc:ID`	Always	`originatorDocumentReference`.
Additional document references	Optional	Entries from `identifiers`.
`cac:AccountingSupplierParty`	Always	Trusted issuer and optional store context.
`cac:AccountingCustomerParty`	Optional	Resolved receiving-party context.
`cac:TaxTotal`	Always	`totalTaxAmount` plus zero or more tax subtotals.
`cac:LegalMonetaryTotal`	Always	Credit-note subtotal, tax-exclusive total, tax-inclusive total, and payable amount.
`cac:CreditNoteLine`	One or more	One element per credited product.

Structured jurisdictional legal text may add a UBL extension namespace and extension content.

Monetary mapping

Merchant property	UBL element
`creditNoteSubtotal`	`cac:LegalMonetaryTotal/cbc:LineExtensionAmount`
`totalBeforeTax`	`cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount`
`totalAmount`	`cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount` and `cbc:PayableAmount`
`totalTaxAmount`	`cac:TaxTotal/cbc:TaxAmount`
Tax `taxableAmount`	`cac:TaxSubtotal/cbc:TaxableAmount`
Tax `amount`	`cac:TaxSubtotal/cbc:TaxAmount`

Amounts carry the currencyID attribute from currency.

Line mapping

Each product becomes cac:CreditNoteLine:

Product property	UBL element
`identifier`	`cbc:ID`
`quantity` and `unitCode`	`cbc:CreditedQuantity` and its `unitCode` attribute
`subtotal`	`cbc:LineExtensionAmount`
`period`	`cac:InvoicePeriod`
`discounts` / `charges`	`cac:AllowanceCharge`
Product name, description, brand, identifiers, barcodes, and tax category	`cac:Item` subtree
`unitPrice` and `baseQuantity`	`cac:Price` subtree

Use positive credit quantities and amounts. UBL CreditNote and CreditedQuantity already communicate the credit direction.

Example skeleton

<CreditNote xmlns="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
            xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
            xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:ID>CN-2026-0042</cbc:ID>
  <cbc:UUID>01234567-89ab-4def-8123-456789abcdef</cbc:UUID>
  <cbc:IssueDate>2026-08-05</cbc:IssueDate>
  <cbc:IssueTime>14:30:22Z</cbc:IssueTime>
  <cbc:CreditNoteTypeCode listAgencyID="6" listID="UN/ECE 1001 Subset">381</cbc:CreditNoteTypeCode>
  <cbc:DocumentCurrencyCode listAgencyID="6" listID="ISO 4217 Alpha">EUR</cbc:DocumentCurrencyCode>
  <cac:OriginatorDocumentReference>
    <cbc:ID>INV-2026-0042</cbc:ID>
  </cac:OriginatorDocumentReference>
  <!-- supplier, optional customer, tax totals, and legal monetary total -->
  <cac:CreditNoteLine>
    <cbc:ID>SKU-AIRMAX-BLK-42</cbc:ID>
    <cbc:CreditedQuantity unitCode="C62">1</cbc:CreditedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">100.00</cbc:LineExtensionAmount>
    <!-- item and price -->
  </cac:CreditNoteLine>
</CreditNote>

Verification

Cheqi hashes UBL XML after exclusive XML canonicalization with SHA-256. Do not compare the raw serialized string when whitespace or namespace formatting may differ.