# 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:

```text
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

```xml
<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.

## Related

- [Issuing Credit Notes](/creditnote/issuing-credit-notes)
- [Credit Notes](/creditnote/credit-notes)
- [Receipt & Credit Note Verification](/verification/verification)