{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"UBL XML Credit Note Format","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"ubl-xml-credit-note-format","__idx":0},"children":["UBL XML Credit Note Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a recipient accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_CREDIT_NOTE"]},", an owner device generates a UBL 2.1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditNote"]}," alongside the CHEQI JSON representation. Both documents describe the same definitive merchant values and share the same document UUID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The root namespace is:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The document also declares the standard UBL Common Aggregate Components (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac"]},") and Common Basic Components (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc"]},") namespaces."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generated-elements","__idx":1},"children":["Generated elements"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Element"},"children":["Element"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Present"},"children":["Present"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Source"},"children":["Source"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:UBLVersionID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Constant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2.1"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documentNumber"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:UUID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptUuid"]},", shared with CHEQI JSON."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:IssueDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date portion of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issueDate"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:IssueTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time portion of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issueDate"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:CreditNoteTypeCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["381"]}," using the UN/ECE 1001 subset."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:Note"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issuer's configured company receipt text. The legacy request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["note"]}," is ignored."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:DocumentCurrencyCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", identified as ISO 4217 alpha."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:OriginatorDocumentReference/cbc:ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorDocumentReference"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional document references"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entries from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:AccountingSupplierParty"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Trusted issuer and optional store context."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:AccountingCustomerParty"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolved receiving-party context."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:TaxTotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalTaxAmount"]}," plus zero or more tax subtotals."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:LegalMonetaryTotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credit-note subtotal, tax-exclusive total, tax-inclusive total, and payable amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:CreditNoteLine"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One element per credited product."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Structured jurisdictional legal text may add a UBL extension namespace and extension content."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"monetary-mapping","__idx":2},"children":["Monetary mapping"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Merchant property"},"children":["Merchant property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"UBL element"},"children":["UBL element"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditNoteSubtotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:LegalMonetaryTotal/cbc:LineExtensionAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalBeforeTax"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:PayableAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalTaxAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:TaxTotal/cbc:TaxAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tax ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxableAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:TaxSubtotal/cbc:TaxableAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tax ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:TaxSubtotal/cbc:TaxAmount"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Amounts carry the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currencyID"]}," attribute from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"line-mapping","__idx":3},"children":["Line mapping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each product becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:CreditNoteLine"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Product property"},"children":["Product property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"UBL element"},"children":["UBL element"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:ID"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quantity"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unitCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:CreditedQuantity"]}," and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unitCode"]}," attribute"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subtotal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cbc:LineExtensionAmount"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["period"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:InvoicePeriod"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discounts"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["charges"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:AllowanceCharge"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Product name, description, brand, identifiers, barcodes, and tax category"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:Item"]}," subtree"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unitPrice"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseQuantity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cac:Price"]}," subtree"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use positive credit quantities and amounts. UBL ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditNote"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditedQuantity"]}," already communicate the credit direction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-skeleton","__idx":4},"children":["Example skeleton"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"<CreditNote xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2\"\n            xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\"\n            xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\">\n  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>\n  <cbc:ID>CN-2026-0042</cbc:ID>\n  <cbc:UUID>01234567-89ab-4def-8123-456789abcdef</cbc:UUID>\n  <cbc:IssueDate>2026-08-05</cbc:IssueDate>\n  <cbc:IssueTime>14:30:22Z</cbc:IssueTime>\n  <cbc:CreditNoteTypeCode listAgencyID=\"6\" listID=\"UN/ECE 1001 Subset\">381</cbc:CreditNoteTypeCode>\n  <cbc:DocumentCurrencyCode listAgencyID=\"6\" listID=\"ISO 4217 Alpha\">EUR</cbc:DocumentCurrencyCode>\n  <cac:OriginatorDocumentReference>\n    <cbc:ID>INV-2026-0042</cbc:ID>\n  </cac:OriginatorDocumentReference>\n  <!-- supplier, optional customer, tax totals, and legal monetary total -->\n  <cac:CreditNoteLine>\n    <cbc:ID>SKU-AIRMAX-BLK-42</cbc:ID>\n    <cbc:CreditedQuantity unitCode=\"C62\">1</cbc:CreditedQuantity>\n    <cbc:LineExtensionAmount currencyID=\"EUR\">100.00</cbc:LineExtensionAmount>\n    <!-- item and price -->\n  </cac:CreditNoteLine>\n</CreditNote>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification","__idx":5},"children":["Verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":6},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/creditnote/issuing-credit-notes"},"children":["Issuing Credit Notes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/creditnote/credit-notes"},"children":["Credit Notes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/verification/verification"},"children":["Receipt & Credit Note Verification"]}]}]}]},"headings":[{"value":"UBL XML Credit Note Format","id":"ubl-xml-credit-note-format","depth":1},{"value":"Generated elements","id":"generated-elements","depth":2},{"value":"Monetary mapping","id":"monetary-mapping","depth":2},{"value":"Line mapping","id":"line-mapping","depth":2},{"value":"Example skeleton","id":"example-skeleton","depth":2},{"value":"Verification","id":"verification","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"UBL XML Credit Note Format","description":"Current UBL CreditNote structure generated by Cheqi owner devices","seo":{"title":"UBL XML Credit Note Format"}},"lastModified":"2026-08-05T15:06:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/creditnote/ubl-format","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}