ICV (Invoice Counter Value)

By Matheel, from ZATCA's specifications and SDK 3.4.8 · Updated

ICV is the sequential counter every ZATCA e-invoicing device (EGS) stamps on each invoice and note it issues: it starts at 1 and goes up by one. Rule BR-KSA-33.

ICV stands for Invoice Counter Value. Every e-invoice generation device (EGS) keeps its own counter that starts at 1 and goes up by one for every document it issues: invoices, credit notes and debit notes, with no gaps. Together with the previous invoice hash (PIH) it chains a device's documents into one sequence.

In the XML (field KSA-16) it sits in a cac:AdditionalDocumentReference whose cbc:ID is ICV, with the number in cbc:UUID. It is not the invoice number (the root cbc:ID) and not the invoice UUID.

What goes wrong: a missing or empty ICV fails BR-KSA-33, an error that rejects the invoice. A value with letters, such as INV-10, fails BR-KSA-34 because the counter must be digits only. Many write-ups blame BR-KSA-16 for counter problems; BR-KSA-16 is actually the payment means code rule.

Advance the counter only after ZATCA answers cleared or reported. A rejected invoice does not use up a number: fix it and resend it with the same counter.

On Matheel, the device_token carries the device's last counter, so Matheel sets the next one itself, refuses a counter that does not match, and answers 409 device_token_reused if two tills share one token.

Example

<cac:AdditionalDocumentReference>
    <cbc:ID>ICV</cbc:ID>
    <cbc:UUID>10</cbc:UUID>
</cac:AdditionalDocumentReference>

FAQ

Is the ICV the same as the invoice number?

No. The invoice number (cbc:ID) is yours to choose and may contain letters, like INV-1001. The ICV is a digits-only counter in cbc:UUID inside the ICV document reference.

What happens to the counter when ZATCA rejects an invoice?

Nothing. A rejected invoice does not consume a value: fix it and resend with the same counter, and advance only after acceptance.

Do credit notes get their own ICV?

Yes. Credit and debit notes are documents in the same device chain, and each takes the next counter value.

Related ZATCA rules

Related terms

Let Matheel handle this for you

Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.

Try Matheel, no signup Matheel API docs