The Invoice Header is the first block of XML fields that defines the invoice before any line or amount. When your system builds the e-invoice file under Phase Two in Saudi Arabia, these are the fields the Fatoora platform reads first to decide the document type, who issued it, when, and in which currency. A single error in the header is enough to reject the whole invoice before the system even reaches the lines. This technical reference explains every field in the header in its actual UBL 2.1 wording, with ready XML snippets and reference tables for every value.
This guide is part of the e-invoicing technical documentation series. For an overview of the invoice file’s general shape and the order of its major blocks, refer to Invoice Structure. The details of lines, amounts, and taxes at the line level are the subject of the separate “Invoice Lines” guide. Here we focus exclusively on the header fields: invoice number, unique identifier, date and time, invoice type code and its subtype, currency, references, and notes.
What is the Invoice Header in XML?
In the UBL 2.1 standard adopted by the Zakat, Tax and Customs Authority (ZATCA), the invoice is a single root element named <Invoice>. Beneath it come two groups of information: document-level fields that describe the invoice as a single unit, and repeating fields that describe the parties and lines. The header is the first section: the fields that appear directly under the root element and before the party blocks (seller and buyer) and before the invoice lines.
These fields follow a strict order enforced by UBL’s XSD schema. You cannot reorder the elements as you please. If you placed the date field before the invoice number, schema validation fails and the file is rejected. That is why any certified accounting system follows the sequence the standard defines literally. The Qoyod e-invoicing software generates this order automatically, so you do not need to write XML by hand, but understanding the header structure helps you read invoices and diagnose rejection errors.
Most header fields belong to the cbc namespace (short for Common Basic Components). Fields that carry a sub-structure, such as references, belong to cac (Common Aggregate Components). You will notice these two prefixes in every snippet that follows. The difference between them is simple: cbc elements carry a single value directly, while cac elements group several sub-elements beneath them. Understanding this distinction makes reading any invoice file easier later.
An important note before we go into detail: all values in the following snippets are illustrative examples. You do not write these fields yourself in actual use; your accounting system generates them. The goal of this reference is for you to understand what the system generates, so you can read the invoice with confidence and diagnose any rejection quickly. A brief example of what the start of the file looks like:
This snippet summarizes the heart of the header. In the following sections we break down each field on its own: its value, its format, its constraints, and the impact of an error in it on invoice acceptance.
Invoice Number (cbc:ID)
The cbc:ID field is the sequential invoice number set by your system. It is a human-readable identifier that appears on the printed document, and it is completely different from the UUID unique identifier that systems generate automatically. It may not be empty, and it must be unique within a single entity’s invoice series.
The Authority requires invoice numbering to be sequential and continuous with no unjustified gaps. This means you cannot delete an invoice from the middle and leave a gap in the sequence. If you cancel an invoice, you issue a credit note linked to it instead of deleting it. The number format is free text, but a fixed pattern combining a prefix, a year, and an incrementing number is preferred.
| Property | Value |
|---|---|
| Element name | cbc:ID |
| Mandatory | Mandatory, does not accept empty |
| Data type | String |
| Constraint | Unique within the entity’s series, sequential with no gaps |
| Example | INV-2026-000128 |
Practical rule: let the seller control the number format in a way that suits its internal system, but do not rely on this field alone to guarantee uniqueness at the platform level. Global uniqueness is the job of the next field.
Unique Identifier (cbc:UUID)
The cbc:UUID is a globally unique identifier in UUID version 4 format. The system generates it automatically for every invoice, and it is never written by hand. Its function is to guarantee the invoice’s uniqueness across the entire platform, not just within a single entity. Even if the invoice number cbc:ID matches between two different entities, the UUID inevitably remains different.
A UUID value is made up of 32 hexadecimal digits distributed across five groups separated by hyphens, in the 8-4-4-4-12 pattern. These hyphens are part of the identifier’s standard format and are not prose hyphens. Do not modify the value after it is generated, because it later enters the data on which the digital stamp and the QR code are computed.
| Property | Value |
|---|---|
| Element name | cbc:UUID |
| Mandatory | Mandatory |
| Data type | UUID v4 (text in 8-4-4-4-12 format) |
| Who generates it | The system automatically, not written by hand |
| Example | 3cf5ee18-ee25-44ea-a444-2c37ba7f28be |
The fundamental difference between cbc:ID andcbc:UUID: the first is a commercial number that a human reads and the seller controls, and the second is a technical identifier that systems read and is generated automatically. Both are mandatory, and both appear in the header, but each has a completely different role.
Invoice Number cbc:ID
Unique Identifier cbc:UUID
Issue Date/Time IssueDate/IssueTime
Invoice Type Code InvoiceTypeCode
Invoice Currency DocumentCurrencyCode
References (BillingReference) and Notes
Issue Date and Time (IssueDate and IssueTime)
The moment the invoice is issued is recorded in two separate fields. The first is cbc:IssueDate for the date, and the second is cbc:IssueTime for the time. This separation is intentional in the standard, so do not merge the date and time into a single field.
The date takes the short ISO 8601 format, which is YYYY-MM-DD, that is, year then month then day separated by hyphens. The time takes the HH:MM:SS format on a 24-hour system. The date is always Gregorian in the XML file, even if your system displays the Hijri date in the user interface.
Time precision matters in the simplified invoice (B2C) because the Authority requires reporting within 24 hours of issuance. The issue time is the starting point for computing this deadline. As for the standard tax invoice (B2B), it goes through the real-time clearance path before it is delivered to the buyer, and the issue time remains a reference for chronological ordering within the invoice series.
| The | Format | Example |
|---|---|---|
cbc:IssueDate |
YYYY-MM-DD (Gregorian) |
2026-06-24 |
cbc:IssueTime |
HH:MM:SS (24 hours) |
11:42:18 |
Common error: using a forward slash instead of the regular hyphen in the date, or writing the month before the day in the American style. Both break schema validation. Always adhere to the YYYY-MM-DD format literally.
Invoice Type Code and Subtype (InvoiceTypeCode)
This is the most important field in the header and the most confusing. The cbc:InvoiceTypeCode field carries two values together: the element text itself specifies the base document type, and the name attribute inside the tag carries a seven-digit subtype code that describes additional characteristics of the invoice. Both values must be set together; one alone is not enough.
Element text values: 388, 383, and 381
The element text takes one of three main values defined in the UN code list UNCL1001 adopted by the Authority:
| Code | Document type | Description |
|---|---|---|
388 |
Tax Invoice | The base document for a taxable sale. Includes both the standard and the simplified invoice |
383 |
Debit Note | Increases the value of a previous invoice, such as correcting an amount that was too low |
381 |
Credit Note | Reduces the value of a previous invoice, such as a return or a later discount |
When you issue a debit or credit note (383 or 381), you must link it to the original invoice through the references block explained later. A note pending without a referenced invoice is rejected.
The subtype code in the name attribute
Property name carries a string of seven digits, each digit representing a binary characteristic (present or not present). The first two digits are the most important because they determine whether the invoice is standard or simplified:
| Digit | Means | Value |
|---|---|---|
| First | Standard tax invoice (B2B) | 1 if standard |
| Second | Simplified tax invoice (B2C) | 1 if simplified |
| Third | Third party | 1 when present |
| Fourth | Nominal | 1 when present |
| Fifth | Export | 1 for an export invoice |
| Sixth | Summary | 1 when summarizing |
| Seventh | Self-billed | 1 for self-billing |
Therefore an ordinary standard tax invoice takes the subtype code 0100000, while the simplified invoice takes 0200000. A snippet for a standard invoice:
And a snippet for a simplified invoice (B2C):
Distinguishing between standard and simplified in this field is not a cosmetic detail. The standard one goes through real-time clearance with the Fatoora platform before it is delivered, and the simplified one is delivered to the buyer immediately and then reported within 24 hours. The subtype code is what tells the platform which path to handle.
| Code | Meaning |
|---|---|
| 388 | Tax invoice |
| 381 | Credit Note |
| 383 | Debit Note |
| Subtype 01 | Standard B2B — clearance |
| Subtype 02 | Simplified B2C — reporting within 24 hours |
Document Currency and Tax Currency (DocumentCurrencyCode and TaxCurrencyCode)
The header carries two currency fields. The first, cbc:DocumentCurrencyCode , specifies the currency in which the invoice was drawn up, and the second, cbc:TaxCurrencyCode , specifies the currency in which tax is computed and reported to the Authority.
Both fields take the currency code in ISO 4217 format, made up of three uppercase letters. The Saudi riyal’s code is SAR. In the local market, the value of the two fields is identical at SAR in the vast majority of invoices.
The important rule: the tax currency must always be SAR for entities operating in Saudi Arabia, even if the invoice was drawn up in a foreign currency. So if you issue an export invoice in US dollars, DocumentCurrencyCode becomes USD, while TaxCurrencyCode becomes SARremains, and a tax exchange rate field is then added within the invoice. This ensures the tax value always reaches the Authority in the local currency.
| The | Function | Value in the local market |
|---|---|---|
cbc:DocumentCurrencyCode |
Invoice drawing currency | SAR (or a foreign currency for export) |
cbc:TaxCurrencyCode |
Currency for computing and reporting tax | SAR always |
Currency codes remain in uppercase Latin letters inside the file, as they are standard identifiers that are not translated. Do not write “riyal” as text in this field; use the code SAR only.
References: Original Invoice, Order, and Contract (Billing References)
The references block links the invoice to other documents. The most important of all is the original invoice reference in the case of debit and credit notes. When the text of InvoiceTypeCode is 383 or 381, this block becomes mandatory because a note has no meaning without the invoice it amends.
This block comes in the cac namespace because it is aggregate and contains sub-elements. An example of linking a credit note to its original invoice:
Here the inner element cbc:ID carries the number of the original invoice that the note amends. This differs from the cbc:ID in the header, which carries the note’s own number. Paying attention to this difference is important, because the file contains two identifiers with the same element name but in two different positions, each pointing to a different document.
Alongside the invoice reference, the header may contain other optional references linking the invoice to the procurement cycle:
| Reference | Element | Mandatory |
|---|---|---|
| Original invoice (for notes) | cac:BillingReference |
Mandatory for 383 and 381 |
| Purchase order | cac:OrderReference |
Optional |
| Contract | cac:ContractDocumentReference |
Optional |
| Additional document | cac:AdditionalDocumentReference |
Optional, used for the QR code and application data |
is also used cac:AdditionalDocumentReference to carry the application data identifier and the QR code generated after the invoice is signed. Although it appears in the header, its content depends on the digital signing process carried out via the entity’s CSID certificate.
Let your system build the invoice header for you
Qoyod generates the header fields in full according to the UBL 2.1 standard and Phase Two requirements automatically, from the invoice number to the type code and currency, without any manual XML writing.
Notes (cbc:Note)
The cbc:Note An optional free-text field that carries a note at the level of the whole document. It is used to add information concerning the entire invoice that does not belong to a specific line, such as the reason for issuing a credit note or a general payment term.
Although the field is optional in an ordinary invoice, it becomes practically important in debit and credit notes, where good practice requires clarifying the reason for the amendment. The field may repeat for more than one note, but do not overuse it, because structured data is always better than free text for automated processing.
| Property | Value |
|---|---|
| Element name | cbc:Note |
| Mandatory | Optional |
| Data type | Free text |
| Repeatability | Yes, more than one note is possible |
Profile Identifier and Counter Value (ProfileID and ICV)
The header’s description is completed by two technical fields that describe the invoice’s context within the platform. The first, cbc:ProfileID , specifies the version of the business file that the invoice follows, and its fixed value in Phase Two is reporting:1.0. This field usually appears at the start of the header before the invoice number.
The second is the Invoice Counter Value, known by the abbreviation ICV. It is an incrementing sequential number that links each invoice to its predecessor to ensure an unbroken sequence within the entity’s series. It comes within cac:AdditionalDocumentReference with the identifier ICV:
The counter value here (128) relates to the invoice’s order within the series, and is used together with the Previous Invoice Hash to build a connected integrity chain. This linkage is what prevents tampering with invoices or deleting them from the middle without a trace.
These two fields are generated by the system automatically according to the state of the entity’s invoice series. Do not intervene in them manually, because any disruption in the counter sequence breaks the integrity chain and leads to the rejection of subsequent invoices.
A Complete Example: Standard vs. Simplified Invoice Header
To cement understanding, here we place two complete headers side by side. The first is for a standard tax invoice (B2B) directed to a tax-registered entity, and the second is for a simplified invoice (B2C) directed to an end consumer. Note that the fundamental difference between them appears in a single field: the subtype code inside the name attribute.
Standard tax invoice header (B2B):
Simplified invoice header (B2C):
The two values are identical in the text of InvoiceTypeCode (388 because both are sale invoices), and the only difference is in the name attribute: the standard one begins with 01 and the simplified one with 02. This small difference decides the entire path: the standard one goes to real-time clearance, and the simplified one to reporting within 24 hours. Many early rejection cases arise from an error in this digit alone.
The practical differences between the two headers also appear in later blocks outside the header. The standard invoice requires the buyer’s full tax data, while the simplified one may suffice with less data about the buyer. But at the header level itself, the subtype code remains the deciding factor.
Additional Document References in Detail
The cac:AdditionalDocumentReference block deserves a pause, as it appears more than once in the header with different identifiers, and each appearance has a role. The three most prominent identifiers used by Phase Two:
| Identifier value | What it carries | When it appears |
|---|---|---|
ICV |
The sequential invoice counter value | In every invoice |
PIH |
The Previous Invoice Hash | In every invoice to build the integrity chain |
QR |
The QR code data | After the invoice is signed |
The identifier PIH carries a hashed value of the invoice that immediately preceded this invoice in the series. The first invoice in the series takes a fixed starting value. Each subsequent invoice carries the hash of its predecessor, forming a connected chain that is impossible to tamper with without detection. An example of a Previous Invoice Hash block:
The value here is encoded in Base64. Do not try to read or modify it manually, as it is the output of an automated hashing process. Any change to it breaks the integrity chain and leads to the rejection of the current invoice and everything after it.
As for the purchase order, it comes in a separate block, cac:OrderReference, and it is optional but useful for linking the invoice to the purchase order that preceded it in the procurement cycle:
Adding these optional references does not affect invoice acceptance, but it enriches its data and facilitates later accounting matching between the invoice, the purchase order, and the contract. A good accounting system fills them automatically when available in the document cycle.
How Does the System Validate the Header Before Sending?
Before any certified system sends the invoice to the Fatoora platform, the file passes through a series of automated checks on the header. A good understanding of these checks helps you interpret rejection messages quickly.
The first check is schema validation (XSD Validation). The schema confirms the presence of the mandatory fields, the correctness of the data types, and the correct order of the elements. If cbc:UUID is missing or the date comes in a wrong format, this check fails immediately.
The second check is the business rules check (Business Rules). Here deeper logic is applied: Is the credit note linked to an original invoice? Does the subtype code match the invoice type? Is the tax currency SAR? These rules are not checked by the schema alone.
| Validation layer | What it checks on the header |
|---|---|
| Schema validation (XSD) | Presence of mandatory fields, data types, order of elements |
| Business rules | Linking the note to its invoice, matching the subtype code with the type, tax currency |
| Chain integrity | ICV counter sequence and Previous Invoice Hash with no gaps |
The most common rejection reasons at the header level are: a subtype code that does not match the invoice type, a date in a wrong format, a credit note without an invoice reference, and a tax currency other than SAR. Getting these four right resolves most early rejection cases.
XSD schema audit
BR-KSA business rules
Chain integrity via the Fatoora platform
Good Practices When Handling Header Fields
Even with automated generation, there are configuration decisions the entity owner makes that affect the cleanliness of the header. Adhering to them reduces rejection cases and facilitates later accounting review.
First, fix a single pattern for the invoice number cbc:ID and do not change it in the middle of the fiscal year. Changing the pattern confuses the sequence and makes tracking harder. A good pattern combines a prefix that distinguishes the document type (such as INV for invoices, SI for simplified, and CN for credit notes) with the year and an incrementing number with a fixed digit count.
Second, do not reuse an invoice number that was previously issued, even if you canceled the original invoice. The sequence must remain connected, and cancellation is done via a credit note, not by recycling the number. This rule protects chain integrity and spares you audit remarks.
Third, make sure your system’s settings set the tax currency TaxCurrencyCode to SAR always for local entities. This setting is easy to overlook when dealing with international clients, but it is a basic condition for the invoice to be accepted by the Authority.
Fourth, when issuing a debit or credit note, always verify the correctness of the original invoice number inside cac:BillingReference. A wrong number here means linking the note to an incorrect or non-existent invoice, and both lead to rejection. Good systems allow selecting the original invoice from a list instead of typing its number manually, which eliminates this error at its root.
| Practice | Benefit |
|---|---|
| A fixed pattern for the invoice number | A clear sequence and easy tracking |
| Not recycling numbers | Chain integrity with no gaps |
| Setting the tax currency to SAR | Guaranteed acceptance by the Authority |
| Selecting the original invoice from a list | Correct references for notes |
Where Does the Header Sit Among the Rest of the Invoice’s Parts?
Once the header fields are complete, it is the turn of the following blocks in the file, in order: the seller block, then the buyer block, then the tax totals, then the invoice lines. The header alone is not enough for a valid invoice, but it is the foundation on which everything after it is built.
For an overview of the full picture of the order of these blocks and their relationship to one another, see the Invoice Structureguide. And to go deeper into how lines, quantities, and taxes are represented at the line level, that is the subject of the separate Invoice Lines guide, which complements this reference.
And to understand the standard on which all these fields are built, see the UBL 2.1 standard that defines the namespaces and elements, and the Invoice Schema that enforces the structural constraints. As for an overview of the invoice file in XML format, you will find it in the XML Invoiceguide. And the certificate with which the file is signed after the header is complete is explained in the CSID Certificate.
A Reference Summary of the Header Fields
The following table gathers all the header fields we explained in one place, to be a quick reference while reading an invoice or diagnosing a rejection:
| The | Function | Mandatory |
|---|---|---|
cbc:ProfileID |
Business file version | Mandatory (reporting:1.0) |
cbc:ID |
The commercial invoice number | Mandatory |
cbc:UUID |
The globally unique identifier | Mandatory |
cbc:IssueDate |
Issue date | Mandatory |
cbc:IssueTime |
Issue time | Mandatory |
cbc:InvoiceTypeCode |
Document type and subtype | Mandatory |
cbc:DocumentCurrencyCode |
Invoice currency | Mandatory |
cbc:TaxCurrencyCode |
Tax currency | Mandatory (SAR) |
cac:BillingReference |
The original invoice reference | Mandatory for notes |
cbc:Note |
A document-level note | Optional |
The header is the first gateway to invoice acceptance. When its fields are correct and consistent, the file passes smoothly to the stage of validating the lines and totals. And the good news is that you are not required to write any of these fields manually: the certified accounting system generates them according to the standard on every invoice, and handles the signing and the linkage with the Fatoora platform on your behalf.
