The UBL 2.1 Standard in the E-Invoice

When discussing the technical structure of e-invoicing in Saudi Arabia, one name sits at the heart of every XML file that billing systems generate: the UBL 2.1 standard. This standard is the language digital invoices speak, and the template on which the Zakat, Tax and Customs Authority (ZATCA) built its Phase Two requirements. Understanding it is essential for every developer building an integration with the Fatoora platform, and for every accountant who wants to know what happens inside the invoice their system issues.

This technical guide focuses on the UBL 2.1 standard alone: what it is, why the Authority chose it, how its namespaces are built, what document types it defines, and how the Authority extended it in its own configuration profile (ZATCA Profile). For the general explanation of why XML was adopted in the first place, see the article XML Invoice: The Technical Format of the E-Invoice, and file validation via the XSD schema is covered in The Invoice Schema and Its Validation.

What is the UBL 2.1 standard?

The abbreviation UBL stands for Universal Business Language. It is an open international standard that defines a set of electronic business documents in XML: the invoice, purchase order, despatch advice, credit note, debit note, and others. Its development is overseen by OASIS, a non-profit global standards body.

Version 2.1 of the standard was released in 2013 and was later adopted as an international standard under the number ISO/IEC 19845:2015. This international adoption matters: it means an invoice built on UBL 2.1 is not a local Saudi format, but a document that any system in the world supporting the same standard can understand.

The strength of UBL lies in the fact that it separates structure frommeaning. Structure is the tree of elements in the XML file, and meaning is what each element represents in the actual commercial context. This separation lets different systems exchange invoices without a prior agreement on the file’s shape, because the standard itself defines everything.

The difference between UBL and “the e-invoice”

Many people confuse the two terms. The e-invoice is a regulatory concept: an invoice issued and stored in a structured digital format instead of on paper. UBL 2.1, on the other hand, is the specific technical template the Authority chose for writing that invoice. In other words: the e-invoice is the “what,” and UBL 2.1 is the “how.” You can read the full regulatory requirements on the E-Invoicing from Qoyod.

Why did the Authority choose the UBL 2.1 standard?

The choice of UBL 2.1 was not random. Clear technical and regulatory reasons stood behind it:

• An adopted international standard: its adoption under ISO/IEC 19845 gives it global legitimacy and makes it easier to deal with foreign companies and international systems.
• Alignment with the European standard: UBL 2.1 aligns with the European semantic standard EN 16931, considered the leading reference for e-invoicing worldwide. Choosing a well-known base reduces risk and provides ready-made libraries.
• Extensibility: UBL allows extension elements to be added without breaking the core structure. The Authority used this capability to add the digital signature and stamp data, as we will see later.
• Abundance of tooling: mature software libraries exist for processing UBL in most programming languages, which lowers the cost of building compliant systems.
• Separation of data from presentation: a UBL file carries data only, while the visual presentation is left to a separate layer. This makes automated auditing and processing easier.

The Authority adopted the UBL 2.1 standard as the basis for the format of the tax invoice and the simplified tax invoice in Phase Two of e-invoicing, which began on 1 January 2023 in waves according to the establishment’s revenue size.

The structure of a UBL 2.1 file: the root element

Every UBL invoice file begins with a single root element named Invoice. This element carries the namespace definitions that bind the file to the UBL standard and to the shared components. Here is the general structure of the root element as it appears in an invoice compliant with the Authority’s requirements:

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
         xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
    <!-- Invoice content here -->
</Invoice>

Notice that the root element defines four namespaces. Each one has a specific role, and this leads us to the most important concept in the standard.

Namespaces: cbc, cac, and ext

A namespace in XML is a way to group elements under a single umbrella and avoid naming conflicts. UBL 2.1 has three core namespaces that every developer needs:

cbc: Common Basic Components

The prefix cbc stands for Common Basic Components. These elements carry a single value: text, a number, a date, or an identifier. They contain no child elements. They are the leaves in the invoice tree.

<cbc:ID>INV-2026-00145</cbc:ID>
<cbc:IssueDate>2026-06-23</cbc:IssueDate>
<cbc:IssueTime>14:30:00</cbc:IssueTime>
<cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>

In this example: cbc:ID is the invoice number, andcbc:IssueDate the issue date, andcbc:DocumentCurrencyCode the document currency (the Saudi riyal, SAR). The value 388 in InvoiceTypeCode is the international code for the tax invoice per the UN/CEFACT list.

cac: Common Aggregate Components

The prefix cac stands for Common Aggregate Components. These elements are aggregating: they contain other child elements, whether cbc or cac. They are the branches in the invoice tree. Example: the seller’s data is aggregated inside a single cac element:

<cac:AccountingSupplierParty>
    <cac:Party>
        <cac:PartyIdentification>
            <cbc:ID schemeID="CRN">1010101010</cbc:ID>
        </cac:PartyIdentification>
        <cac:PostalAddress>
            <cbc:StreetName>King Fahd Road</cbc:StreetName>
            <cbc:CityName>Riyadh</cbc:CityName>
            <cbc:PostalZone>12345</cbc:PostalZone>
            <cac:Country>
                <cbc:IdentificationCode>SA</cbc:IdentificationCode>
            </cac:Country>
        </cac:PostalAddress>
        <cac:PartyTaxScheme>
            <cbc:CompanyID>300000000000003</cbc:CompanyID>
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:PartyTaxScheme>
    </cac:Party>
</cac:AccountingSupplierParty>

Notice the nesting: cac:AccountingSupplierParty contains cac:Party, which in turn contains other cac elements (the address, the tax scheme) and terminal cbc elements (the name, the city, the 15-digit tax number). This structured nesting is the essence of the UBL structure.

ext: extension elements

The prefix ext stands for Common Extension Components. This namespace is dedicated to adding data outside the standard structure without breaking the standard. This is where the Authority places the digital signature and stamp data. We return to it in detail in the Saudi configuration profile section.

The relationship of UBL 2.1 to the European standard EN 16931

The Authority’s choice of the UBL 2.1 standard cannot be understood in isolation from the European standard EN 16931. This European standard is not a file format, but a semantic model: a list of the fields any e-invoice must contain, their meanings, and the business rules governing the relationships between them. An example of a business rule: “the invoice total before tax must equal the sum of the line item amounts.”

The European standard defines “what” information the invoice must carry, but it does not dictate “how” that information is written in a file. To apply it in practice, it needs a technical syntax to carry these fields. The European Union adopted two official syntaxes: UBL 2.1 and the UN/CEFACT CII syntax. The Saudi Authority chose the first.

This linkage explains why you find UBL element names matching the European standard’s fields conceptually. Every semantic field in EN 16931 has a counterpart in the UBL structure. The practical benefit: companies that built systems for the European market find a large part of their work reusable in the Saudi market, adjusting only the configuration profile layer.

Element ordering rules (cardinality and sequence)

One of the things that surprises developers new to UBL most is that element ordering is mandatory. The schema defines, for each cac element, the exact sequence of its child elements and how many times each element may repeat (cardinality): mandatory once, optional, or repeatable. Placing an element cbc:IssueDate after cbc:InvoiceTypeCode instead of before it is enough to fail validation, even if all the values are correct.

This strictness is intentional: it allows fast automated validation via the schema without the need for additional logic. But it means the developer must follow the schema’s order literally. That is why most developers rely on ready-made generation libraries instead of building XML by hand, because the library guarantees the correct order automatically.

The document types UBL 2.1 defines

UBL 2.1 defines more than 65 commercial document types, but in the context of Saudi e-invoicing three main types concern us, each identified via the cbc:InvoiceTypeCode:

The credit note and debit note use a root element different from the invoice: CreditNote fromDebitNote respectively, but the internal structure and logic are the same. Each note must reference the original invoice it amends via the cac:BillingReference.

Distinguishing the standard invoice from the simplified one

In addition to the international code, the Authority distinguishes between the standard invoice (B2B) and the simplified one (B2C) via the name attribute inside InvoiceTypeCode. This attribute carries a seven-digit string, each digit carrying a meaning:

<cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
<!-- First/second digit: 01 = standard invoice, 02 = simplified invoice -->

This distinction is fundamental because it determines the technical path: the standard invoice requires prior clearance from the Fatoora platform before it is delivered to the buyer, while the simplified invoice is issued to the buyer immediately and reported to the Authority within 24 hours.

How did the Authority extend the UBL 2.1 standard?

The standard on its own is not enough for Phase Two requirements. The Authority added a layer of mandatory requirements on top of UBL 2.1, known as the configuration profile (ZATCA Profile). This layer does not break the standard; instead, it uses the extension mechanisms built into it.

UUID: the invoice’s unique identifier

The Authority requires a globally unique identifier for every invoice, in addition to the sequential invoice number. This identifier is added via the cbc:UUID:

<cbc:ProfileID>reporting:1.0</cbc:ProfileID>
<cbc:ID>INV-2026-00145</cbc:ID>
<cbc:UUID>3cf5ee18-ee25-44ea-a444-2c37ba7f28be</cbc:UUID>

element. The cbc:ID element is the sequential number the user sees, while the cbc:UUID is a unique technical identifier that never repeats between any two invoices across the entire system.

Previous Invoice Hash

To ensure the integrity of the invoice chain and prevent tampering, the Authority links every invoice to the one preceding it via a hash fingerprint. This fingerprint is stored inside an extension element and is computed with the SHA-256 algorithm. This builds an interlinked chain: if an invoice is deleted or altered, the chain breaks and the tampering shows up immediately.

The digital signature and stamp

The most important Saudi addition is the digital signature. The invoice is signed using a PKI certificate issued by the Authority, known as the Cryptographic Stamp Identifier (CSID). The signature is placed inside the ext:UBLExtensions element in the file header:

<ext:UBLExtensions>
    <ext:UBLExtension>
        <ext:ExtensionURI>urn:oasis:names:specification:ubl:dsig:enveloped:xades</ext:ExtensionURI>
        <ext:ExtensionContent>
            <sig:UBLDocumentSignatures
                 xmlns:sig="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2">
                <!-- Digital signature and stamp data here -->
            </sig:UBLDocumentSignatures>
        </ext:ExtensionContent>
    </ext:UBLExtension>
</ext:UBLExtensions>

This use of the ext:UBLExtensions element is a textbook example of the UBL philosophy: instead of modifying the standard’s structure, the Authority places its own data in the container dedicated to extension. Any system that reads the file and understands UBL will recognize the core structure, even if it does not understand the extension’s content.

The QR quick-response code

The Authority requires a QR code embedded in the invoice, carrying essential data encoded in TLV (Tag-Length-Value) format and converted to Base64. It is stored inside a cac:AdditionalDocumentReference element named QR:

<cac:AdditionalDocumentReference>
    <cbc:ID>QR</cbc:ID>
    <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">
            AQ1Rb3lvZCBDb21wYW55Ag8zMDAwMDAwMDAwMDAwMDM...
        </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
</cac:AdditionalDocumentReference>

The structure of invoice line items in UBL 2.1

Each line in the invoice is represented by an cac:InvoiceLineelement. This element aggregates the quantity, price, description, and tax for a single line item:

<cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="PCE">10</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="SAR">1000.00</cbc:LineExtensionAmount>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
        <cbc:RoundingAmount currencyID="SAR">1150.00</cbc:RoundingAmount>
    </cac:TaxTotal>
    <cac:Item>
        <cbc:Name>Accounting advisory service</cbc:Name>
        <cac:ClassifiedTaxCategory>
            <cbc:ID>S</cbc:ID>
            <cbc:Percent>15.00</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:ClassifiedTaxCategory>
    </cac:Item>
    <cac:Price>
        <cbc:PriceAmount currencyID="SAR">100.00</cbc:PriceAmount>
    </cac:Price>
</cac:InvoiceLine>

In this example: a single line item with a quantity of 10 units, a unit price of 100 Saudi riyals, a line total before tax of 1,000 riyals, a value-added tax of 15% (i.e. 150 riyals), and a total including tax of 1,150 riyals. The code S in ClassifiedTaxCategory means standard rated.

Invoice totals

The totals are aggregated in the cac:LegalMonetaryTotalelement, which carries the amount before and after tax and the amount due:

<cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="SAR">1000.00</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="SAR">1000.00</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="SAR">1150.00</cbc:TaxInclusiveAmount>
    <cbc:PayableAmount currencyID="SAR">1150.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

The total tax is aggregated separately in the cac:TaxTotal element at the level of the whole invoice, with a breakdown per tax category in cac:TaxSubtotal. This separation allows the Authority to automatically verify the correctness of the tax calculations before clearing the invoice.

Why does understanding UBL 2.1 matter to the developer?

If you are building a system that issues compliant invoices, understanding the UBL structure determines the success of the integration. The most common errors in invoices being rejected by the Fatoora platform stem from unsound XML structure: an element in the wrong order, a missing namespace, or a value that does not match the expected data type. The standard is strict: the order of elements inside each cac element is predefined in the schema, and any deviation from it fails validation.

Understanding UBL also helps you read the error messages the platform returns. When a message points to an element like cac:TaxTotal or cbc:TaxAmount, a developer familiar with the standard knows where to look immediately. Whoever treats XML as a black box wastes a lot of time guessing.

Common errors in UBL structure that lead to invoice rejection

From real-world integration with the Fatoora platform, a recurring set of errors is worth the developer’s attention:

• A missing or wrong namespace: forgetting to define the cac or cbc prefix in the root element leaves the platform unable to interpret the elements, so it rejects the entire file.
• Wrong element order: placing a child element out of its position inside a cac element violates the schema sequence and fails validation.
• A non-matching data type: writing a date in a non-ISO format, or a number with an Arabic comma instead of the decimal point, or leaving a mandatory field empty.
• Inconsistent calculations: if the cbc:TaxInclusiveAmount does not equal the sum of the amount before tax and the tax, a business rule is broken and the invoice is rejected.
• A broken hash chain: sending a hash fingerprint that does not actually match the previous invoice breaks the linkage chain.

The practical lesson: building a valid UBL invoice is not just about filling in the fields; it requires respecting the structure, the order, and the business rules together. This is where the value of using a ready-made system that handles all these details, instead of building them from scratch, lies.

Separating data from visual presentation

An important point that is often overlooked: the UBL file carries data only, and does not define the visual shape of the invoice the customer sees. Converting the file into a human-readable image (such as a PDF/A-3 file) happens in a separate layer via a transformation sheet (XSLT) or a display template. This separation is a feature, not a constraint: one system generates the data, and multiple systems may present it in different forms, without touching the data cleared by the Authority.

That is why when you receive an invoice in PDF/A-3 format, it is in fact a container carrying a UBL XML file embedded inside it. The visual image is for the eye, and the digital file is for systems and validation. This duality serves both parties: the accountant reads the invoice easily, and the system validates it automatically.

How does Qoyod help you deal with UBL 2.1?

The good news for business owners: you do not need to write a single line of XML yourself. The Qoyod e-invoicing software handles generating a complete UBL 2.1 file behind the scenes, compliant with Phase Two requirements:

• It generates a UBL 2.1 file for every invoice automatically according to the profile approved by the Authority, with the correct namespaces and element order.
• It adds the unique identifier (UUID), the hash fingerprint, and the interlinked invoice chain without any manual intervention.
• It manages the stamp certificate (CSID) and digitally signs every invoice before sending it.
• It performs prior clearance for standard invoices (B2B) with the Fatoora platform, and reporting within 24 hours for simplified invoices (B2C).
• It generates the QR code in the required TLV format and embeds it in the invoice.

This way the accountant gets a technically compliant invoice with a single click, while the complexity of UBL 2.1 stays hidden inside the system. Technical support is available 24 hours a day, seven days a week to help you connect your establishment to the Fatoora platform.

The UBL invoice lifecycle from generation to clearance

To understand where UBL 2.1 sits within the whole ecosystem, follow the journey of a standard invoice (B2B) from the moment it is created until it reaches the buyer:

• The accounting system generates the UBL 2.1 file with all its mandatory elements: the seller’s and buyer’s data, the line items, the tax, and the totals.
• The system computes the hash fingerprint and links the invoice to its predecessor in the interlinked chain.
• The system digitally signs the invoice with the stamp certificate (CSID) and places the signature inside the extension element.
• The system sends the signed file to the Fatoora platform requesting prior clearance.
• The platform validates the file’s structure, the business rules, and the signature’s validity, then clears the invoice and re-stamps it (Cryptographic Stamp).
• The system delivers the cleared invoice to the buyer, and it becomes a valid tax document.

The simplified invoice (B2C), on the other hand, follows a lighter path: the system issues it to the customer immediately, then reports it to the Fatoora platform within 24 hours. The difference stems from the nature of the transaction: the consumer invoice needs speed at the point of sale, while the business invoice can tolerate the prior clearance step. In both cases, the UBL 2.1 file remains the unified technical container that carries the data.

This journey shows why generating a structurally sound UBL file alone is not enough. Full integration requires dealing with the Fatoora platform’s interfaces, managing the certificates, handling responses and errors, and storing the cleared copies. All these layers are built on top of the UBL 2.1 file, which remains the starting point and the foundation.

UBL 2.1 within the technical documentation series

The UBL 2.1 standard sits at the heart of the technical structure of the e-invoice, but it is not the only piece. To complete the picture:

• To understand why XML was chosen in the first place and how it is read and processed, see XML Invoice: The Technical Format of the E-Invoice.
• To validate the soundness of the file’s structure via the XSD schema and the business rules, see The Invoice Schema and Its Validation.
• To review the full regulatory requirements for value-added tax related to invoicing, see the Value-Added Tax.
• For a comprehensive look at the learning paths around e-invoicing, browse the E-Invoicing section in the Learning Center.

Frequently Asked Questions

What is the difference between UBL 2.0 and UBL 2.1?

Version 2.1 is broader and more mature: it added new document types and additional elements, and was adopted as an international standard under ISO/IEC 19845:2015. The Authority relies exclusively on version 2.1 in its e-invoicing requirements, so the older version is not used.

Do I have to write a UBL file by hand for every invoice?

No. Any accounting system compliant with Phase Two, such as Qoyod, generates the file automatically. Writing XML by hand is impractical and prone to the errors that lead to invoice rejection by the Fatoora platform.

What do the two prefixes cbc and cac mean in the invoice elements?

cbc stands for Common Basic Components, elements that carry a single value such as a number or a date. cac stands for Common Aggregate Components, elements that contain other child elements. Together they build the entire invoice tree.

How does the UBL 2.1 standard ensure the invoice is safe from tampering?

Through the Saudi configuration profile layer: the digital signature inside the extension element, and the hash fingerprint (SHA-256) that links every invoice to its predecessor in an interlinked chain. Any change breaks the chain and shows up immediately upon validation.

Is UBL 2.1 a Saudi-specific standard?

No. It is an open international standard overseen by the OASIS organization, internationally adopted and aligned with the European standard EN 16931. The Authority added a layer of local requirements (ZATCA Profile) on top of it without modifying the core standard.

Where is the digital signature data placed inside the UBL file?

Inside the ext:UBLExtensions element in the file header. This container is designated in the standard for adding data outside the standard structure, so the signature and stamp use it without breaking the UBL structure.