The Unique Identifier (UUID) in the E-Invoice

The Unique Identifier (UUID) is a mandatory field in every e-invoice issued under Phase Two of e-invoicing in Saudi Arabia. Its purpose is simple at its core: it gives each invoice document a global fingerprint that never repeats, distinguishing it from any other invoice issued now or in the future, whether in your system or in any other system in the world. This technical documentation is aimed at the developers and integration engineers who build or connect their systems with the e-invoicing platform and the Fatoora platform of the Zakat, Tax and Customs Authority (ZATCA).

Here we focus on the UUID field alone: what it is, its format, where it sits inside the XML file, how it differs from the human-readable invoice number (cbc:ID) and from the sequential counter ICV, and how accounting systems generate it. The ICV counter field and the Previous Invoice Hash (PIH) field each have separate documentation, which we point to in its place.

What is the Unique Identifier (UUID)?

UUID is short for Universally Unique Identifier. It is a string of 32 hexadecimal digits distributed across five groups separated by four dashes, with a total length of 36 characters. The goal of the standard is for two different systems to generate two values with no coordination between them, while the probability of a match is so small it can be neglected in practice.

In the e-invoicing context, the Authority requires every invoice to carry its own UUID value inside the XML file. This value is the identifier the Fatoora platform uses to distinguish the document during Clearance for business-to-business invoices and Reporting for consumer invoices. The value is generated once when the invoice is created, and never changes afterward.

The standard that governs the UUID structure is RFC 4122. This standard defines several versions of the identifier, differing in the method of generation. The version used in e-invoicing is version 4 (UUID version 4), which is the version built on random numbers, and we will detail it shortly.

The UUID format and its components

A UUID value consists of five groups of hexadecimal characters, in the pattern 8-4-4-4-12. That is eight characters, then four, then four, then four, then twelve, separated by dashes. Here is an actual example of a valid value:

3cf5a3b9-7b1e-4f2a-9c84-1d6e2f0a8b47

Each character takes a value from the set 0-9 anda-f, which is the way of representing the sixteen bytes that make up the identifier (128 bits). The distribution of characters is as follows:

• First group: 8 characters.
• Second group: 4 characters.
• Third group: 4 characters, beginning with the digit 4 in version 4.
• Fourth group: 4 characters, whose first character takes one of the values 8 or 9 or a or b.
• Fifth group: 12 characters.

These two reserved positions (the digit 4 at the start of the third group, and the specific value at the start of the fourth group) are not a cosmetic detail. They are what tell any system reading the value that it is version 4 and that it follows the standard variant layout in RFC 4122. Any correct UUID v4 generator sets these two positions automatically.

Why version 4 specifically?

Version 4 is built on pseudo-random numbers. The system generates 122 random bits (out of 128, after reserving six bits for the version and variant), producing an enormous value space. In practice, this means your system can generate millions of invoices with no realistic concern about repeating a previously generated value.

The advantage of version 4 is that it needs no central coordination, no device address, and no timestamp. Any server, in any branch, at any moment, generates a completely independent value. This property is important for multi-branch or point-of-sale businesses, where many devices issue invoices at the same time without connecting to one another.

Anatomy of the Unique Identifier structure

The internal structure at the bit level

A UUID value is at its core a number 128 bits long, that is 16 bytes. The representation of the thirty-six hexadecimal characters is nothing but a human-readable way of reading these bits. When generating version 4, six bits are reserved for the standard’s purposes: four bits define the version number, set to the binary value corresponding to the digit 4, and two or three bits define the variant and are set to the standard RFC 4122 pattern. The remaining 122 bits are filled with pseudo-random values.

This number of random bits is what gives the identifier its uniqueness. The space of possible values approaches two to the power of one hundred and twenty-two, a number that exceeds any data volume a business would handle in its entire lifetime. It is therefore correct to say that the probability of a collision between two randomly generated values approaches zero in real-world use, without needing any coordination between the generating systems.

This entails an important practical principle: do not rely on the order of UUID values to infer chronological order. The value is entirely random, so it does not indicate which was issued first, nor is it suitable as a key for chronological sorting. If you need a chronological order, rely on the issue date and time cbc:IssueDate andcbc:IssueTime, or on the sequential ICV counter.

Where does the UUID sit inside the XML file?

The Unique Identifier is written in a standalone element named cbc:UUID near the top of the invoice document, within the UBL 2.1 format that Saudi e-invoicing follows. The element comes directly after the human-readable invoice number cbc:ID and before the issue date. Here is a simplified snippet from the header of a tax invoice:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:ID>INV-2026-000142</cbc:ID>
  <cbc:UUID>3cf5a3b9-7b1e-4f2a-9c84-1d6e2f0a8b47</cbc:UUID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  <cbc:IssueTime>13:45:30</cbc:IssueTime>
  <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
</Invoice>

Note the difference between the two lines: cbc:ID carries the invoice number the accountant and customer see (such as INV-2026-000142), while cbc:UUID carries the technical Unique Identifier that systems and the Fatoora platform deal with. Both are mandatory, and each has an entirely different role.

The UUID itself later enters the data over which the cryptographic stamp and the document hash are computed, so it is part of the invoice’s integrity and not a decorative field. Any modification to it after generation corrupts the document and makes it unacceptable to the Authority.

The difference between UUID and the invoice number cbc:ID

This is the point that most confuses developers new to integration. The two fields look similar because both “identify” the invoice, but they differ in purpose, format, and who generates them.

The invoice number cbc:ID is a human-readable commercial serial number. The business chooses it and organizes it as it wishes, usually in an ascending sequence such as INV-2026-000142. This number appears on the customer’s copy, and is used in correspondence and accounting reconciliations. Its essential condition is that it be unique within the business’s own records.

As for cbc:UUID , it is a technical identifier that is neither read nor entered by hand. The system generates it automatically in version 4 format, and it is unique at the global level, not merely at the business level. It carries no sequential meaning, does not indicate an invoice’s order among its peers, and is not meant to be printed by anyone on paper.

A practical rule that helps distinguish them: if the customer asks about their invoice number, you answer with the cbc:IDvalue. But when you query technically about a specific document in the Fatoora platform or in your database, you use the value of cbc:UUID.

UUID versus the invoice number at a glance

Validating the UUID value

Before any system accepts a UUID value, it verifies that it matches the expected format. The check here is purely formal: it does not confirm the “validity” of the invoice, but rather that the string is written in the correct pattern and that it is genuinely version 4. The simplest tool for this is a regular expression that checks the pattern 8-4-4-4-12 and confirms the position of the version digit and the position of the variant.

// UUID v4 validation pattern (lowercase)
^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Note in the expression above that the third group inevitably begins with the digit 4, and that the fourth group begins with one of the values 8 or 9 or a or b. These two conditions are what distinguish version 4 from other versions. If the expression allowed any character in these two positions, it would accept values from other versions that do not comply with the e-invoicing requirement.

The practical rule is to validate the format both at the point of entry and when building the XML file. Early validation prevents a malformed value from leaking into the sent document, and it makes tracing the error easier later. With a compliant system, the value is generated internally in a correct format every time, so validation remains an extra safety layer and nothing more.

Storing the UUID and linking it via the API

The sound practice is to store the UUID value in a dedicated column in the invoices table in the database, linked to the invoice’s primary key. Many databases support a native UUID data type, which is more efficient than storing it as text because it saves the value in 16 bytes instead of 36 characters. If it is stored as text, adopt lowercase and keep the dashes fixed to avoid duplicating the same value in two different formats.

The importance of immutability appears in the API path. When the invoice is sent to the Fatoora platform through the Clearance or Reporting interface, the UUID value is part of the request payload and part of the data over which the stamp was computed. If you generated a new value later and queried with it, it would not match the document that was sent first, so you would lose the ability to link the response to the correct invoice.

That is why the UUID makes an excellent correlation key between your local record and the Authority’s response: you send the invoice with its identifier, receive the response, and link it to the record via the same value. This linkage remains valid as long as the value has not changed since generation, which is an additional reason that generating it once and storing it is a rule that is not broken.

UUID across the invoice lifecycle

The Unique Identifier accompanies the invoice from the moment of its creation until it is archived. The path begins with generating the value when the invoice record is created, then inserting it into the XML file, then having it enter the computation of the cryptographic stamp and the document hash. After that, the path differs slightly between the two invoice types.

In the business-to-business tax invoice, the invoice goes through the Clearance path: it is sent to the Fatoora platform first, the Authority returns a stamped XML copy, and it is then delivered to the customer. The UUID value itself remains fixed throughout this path, and is used to match the returned stamped copy with the local record. As for the simplified consumer invoice, it is delivered immediately, then the Authority is notified of it within 24 hours through the Reporting path, and the value is likewise fixed and used in reporting and matching.

In both cases, the Unique Identifier does not change and is not regenerated. It is the thread that links the local record copy to the Authority’s copy to the customer’s copy. Any difference in the value between these copies means a flaw in the integration that must be detected and resolved before relying on the invoice.

UUID in a multi-branch and point-of-sale environment

The value of the random version 4 shows clearly in multi-branch businesses or those running many points of sale. Each device issues invoices at the same time without connecting to the other devices, yet UUID values do not collide between them, because each value is generated randomly from an enormous space. There is no need for a central server to distribute the identifiers, nor to reserve number ranges for each branch.

This differs fundamentally from the sequential ICV counter. The ICV counter is computed for each device or issuing unit separately, so each device starts from 1 and increases in its own order. As for the UUID, it needs no such separation, because its uniqueness is global by nature, not local. Combining the two gives the business a global distinction for each document and a locally auditable sequence for each device at the same time.

The difference between UUID and the ICV counter

Alongside the invoice number and the Unique Identifier, Phase Two requires a third field: the Invoice Counter Value (ICV). Confusing UUID and ICV is common because both are technical fields generated by the system. But the difference is fundamental.

The ICV counter is an ascending sequential integer that starts from 1 and increases by one with each invoice the same device issues. Its task is to prove that the invoice sequence is continuous with no gap, so if the counter jumps from 50 to 52 that indicates a deleted or missing invoice. That is, ICV is a sequential, ordinal field by nature.

The Unique Identifier (UUID) is the exact opposite: a random value with no order and no succession. From two UUID values you cannot tell which was issued first, whereas the ICV counter tells you that immediately. In short: UUID answers “is this invoice unique?”, and ICV answers “is the invoice sequence continuous?”. Each has a role that the other does not replace, and the ICV counter has its own separate documentation within this technical section.

The relationship of UUID to the Previous Invoice Hash (PIH)

The third technical field in the invoice integrity chain is the Previous Invoice Hash (PIH). It is a SHA-256 fingerprint of the invoice that preceded the current invoice, inserted inside the current invoice to link it to its predecessor in a continuous chain that cannot be tampered with without detection.

Here the role of the UUID appears within the broader system. The Unique Identifier distinguishes the document, the ICV counter proves its sequence, and the PIH links it to what came before it. The three together form the mechanism for proving invoice integrity in Phase Two. Any tampering with any invoice breaks the chain and shows immediately upon validation. The detail of the hashing mechanism and how it is computed is explained in the separate PIH documentation within this section.

The three fields in the invoice integrity chain

How do systems generate the UUID value?

No one writes the UUID value by hand. Ready-made libraries in almost every programming language generate it, and their function is to produce the version 4 value with the two reserved positions set, without the developer’s intervention. Here are examples from the most common environments:

// JavaScript (Node.js 14.17+ or the modern browser)
const uuid = crypto.randomUUID();
// Result: "3cf5a3b9-7b1e-4f2a-9c84-1d6e2f0a8b47"

# Python
import uuid
value = str(uuid.uuid4())

// PHP (ramsey/uuid library)
use Ramsey\Uuid\Uuid;
$value = Uuid::uuid4()->toString();

// Java
import java.util.UUID;
String value = UUID.randomUUID().toString();

The golden rule: generate the value once when the invoice record is created, store it in the database linked to the invoice, then use the stored value in every subsequent step (building the XML, computing the stamp, sending to the Fatoora platform). Do not generate a new value every time you build the file, because that makes the identifier change and corrupts the match with the previously sent document.

Common mistakes when generating a UUID

• Using a version other than 4 (such as version 1, built on time and device address) unintentionally. Verify that the function used is uuid4 or its equivalent.
• Regenerating the value on every build of the file instead of storing it, producing an identifier different from the one previously sent.
• Writing the characters in uppercase when the system expects lowercase. Adopt lowercase to avoid matching discrepancies.
• Inserting the dashes in the wrong positions or omitting them entirely, so the validator rejects the format.
• Confusing the UUID value with the invoice number cbc:ID in the code, so one is placed where the other should be inside the XML.

UUID in the UBL 2.1 format and the QR code

E-invoicing in Saudi Arabia adopts the UBL 2.1 format for the XML document. The cbc:UUID field is a standard part of this format, sits in the document header, and does not repeat. The Unique Identifier does not directly enter the nine required QR-code tags for the simplified invoice, but it is part of the document data on which the cryptographic stamp is built, and the stamp itself is one of the QR tags.

Put more clearly: the Unique Identifier does not appear as text inside the QR, but it affects the computed values (the stamp and the document hash) that appear inside it. That is why the UUID must be fixed and final before any subsequent computation on the invoice.

Why does the validator care about the UUID value?

From an integration perspective, the Unique Identifier is not an optional field filled in to complete the form. It is a component in the system for proving the document’s integrity. When the Fatoora platform receives the document, it expects a correctly formatted UUID value in its place, and expects it to be the same value that entered the computation of the stamp and the hash. Any inconsistency between the declared value and the value computed over is considered a flaw in the document.

This explains why the UUID must be final before any subsequent computation. If you changed the value after computing the stamp, the stamp would be computed over an old value that does not match the declared one, so the validator rejects the document. The rule, then: generate the value first, fix it, then build the rest of the technical fields on top of it in the correct order.

The Unique Identifier also helps in tracing errors. When a problem appears in a specific invoice, you can search for it by its UUID value in your records and in the Authority’s responses without ambiguity, because the value is globally unique and does not repeat between invoices or between systems. This property makes the identifier a practical diagnostic tool alongside its official role.

How does Qoyod handle the Unique Identifier (UUID)?

Qoyod is an accounting system compliant with Phase Two of e-invoicing. When issuing any tax invoice or credit or debit note, Qoyod generates a valid UUID value in version 4 format and inserts it in the correct position inside the XML file built according to UBL 2.1, without any manual setup from the user.

Alongside generating the Unique Identifier, Qoyod builds the full document to Phase Two requirements: the cryptographic stamp via the Cryptographic Stamp Identifier (CSID) issued by the Authority, the QR code, and the invoice hash chain. Qoyod also handles the Clearance path for business-to-business invoices and the Reporting path for consumer invoices with the Fatoora platform. The user issues the invoice as usual while the technical fields are built behind them.

For developers who need the raw file, Qoyod provides an XML download button for the invoice, and also issues a PDF/A-3 copy with the tax XML file embedded inside it as an attachment, matching the human-readable-format requirement in Phase Two. This means a single file for the customer instead of two separate files.

Frequently asked questions about the Unique Identifier (UUID)

Do I have to write the UUID value myself?

No. The value is generated automatically by the system in version 4 format. Any system compliant with Phase Two, such as Qoyod, takes care of this without your intervention.

Can two invoices have the same UUID value?

The probability of repetition in version 4 is so small it can be neglected in practice, due to the vastness of the random value space. That is why the identifier is considered unique at the global level, not merely at the level of your business.

What is the difference between the UUID and the invoice number?

The invoice number cbc:ID The invoice number is a readable commercial serial number set by the business’s accounting system and shown to the customer. As for cbc:UUID , it is a random technical identifier, globally unique, that systems and the Fatoora platform deal with. Both are mandatory.

Where do I find the UUID value in the invoice?

It sits in the element cbc:UUID in the header of the XML file, after the invoice number cbc:ID and before the issue date. It usually does not appear on the printed copy for the customer.

Does the UUID change if I modify the invoice?

The identifier is generated once when the invoice is created and does not change. Any modification to the value after building the document corrupts the stamp and the hash and makes the invoice unacceptable to the Authority. Correction is done via a credit or debit note with its own identifier.

What is the relationship of UUID to the ICV counter and the PIH?

The three together prove the invoice’s integrity: UUID distinguishes the document, the ICV counter proves the sequence’s continuity, and the PIH links the invoice to its predecessor in a tamper-protected chain.

Technical summary

The Unique Identifier (UUID) is a mandatory field in version 4 format, located in the element cbc:UUID inside the XML file in UBL 2.1 format, and it distinguishes each invoice globally. It differs from the human-readable invoice number cbc:ID , from the sequential ICV counter, and from the linking PIH hash. Systems generate it automatically once and store it as fixed. For more on the rest of the technical fields, refer to the documentation of The XML file of the e-invoice andThe structure of the e-invoice, and for the full picture of the regulatory requirements refer to The e-invoicing guide andValue Added Tax.