Why ZATCA rejected your invoice: the eight usual causes

When ZATCA rejects a submitted invoice it returns a validation result with codes and messages. Most rejections come from a small set of causes. Here they are, in roughly the order of how often we see them.

First, an important distinction:warnings andrejections are not the same. A warning means the document was accepted with a note. A rejection means it was not accepted. A system that shows you one number for both is hiding the difference; see thepenalties article.

1. The hash chain is broken

Symptom: rejection referencing the previous invoice hash.

Cause: an invoice was issued out of sequence, a device was restored from a backup, two devices shared an identity, or invoices were submitted in a different order from the one they were issued in.

Fix: stop issuing on that device until the chain is understood. Do not "fix it forward" by starting a new chain — it makes the problem harder to explain. Establish which invoice broke it, and work with your vendor and tax adviser on the correction.

Prevention: one identity per device, never restore a terminal from another terminal's backup, and submit in issue order.

2. Certificate problems

Symptom: rejection referencing the signature or the certificate.

Causes: expired production CSID; the device still using a compliance CSID rather than a production one; a certificate that does not match the VAT number on the invoice.

Fix: re-onboard the device. See theonboarding guide.

3. VAT rounding

Symptom: rejection about totals not matching.

Cause: line-level VAT rounded per line, invoice-level VAT computed on the sum, and the two disagree by a halala. Or a discount applied after VAT instead of before.

Fix: this is a configuration matter, not a data-entry one. Your system must round consistently at the level the specification requires. If your rejection reports are full of one-halala discrepancies, this is it, and your vendor needs to fix it.

4. An invalid buyer VAT number on a standard invoice

Symptom: rejection on a B2B invoice.

Cause: a 15-digit VAT number typed with a transposition, or a commercial registration number entered where the VAT number belongs.

Fix: validate at entry. A VAT registration number has a check structure; a POS that accepts anything 15 characters long is not validating.

5. Timestamp problems

Symptom: rejection about the invoice date and time.

Cause: the terminal's clock is wrong, or the timezone is wrong, or the timestamp is not in the expected ISO 8601 format with the correct offset.

Fix: check the terminal's clock and timezone. A terminal left on a factory timezone is a surprisingly common cause, especially on devices imported directly.

6. Schema errors

Symptom: rejection about the XML structure.

Cause: a field missing, a field in the wrong element, or an unexpected character. Arabic text encoded in something other than UTF-8 causes this.

Fix: vendor-side. Report it with the exact rejection message and the invoice UUID.

7. Duplicate UUID

Symptom: rejection about a document that already exists.

Cause: the same invoice was submitted twice — usually a retry after a timeout where the first attempt actually succeeded.

Fix: your system should treat a duplicate rejection as confirmation, not as a failure to retry forever. If your unreported queue has invoices retrying endlessly, this is likely why.

8. Wrong document type

Symptom: rejection on a credit note.

Cause: the credit note does not reference an original invoice, or references one that does not exist, or is typed as an invoice rather than a note.

Fix: see thecredit note guide.

A triage procedure

When you find rejections:

1. Count them and group by message. Twenty rejections with one message is one bug. Twenty with twenty messages is a data problem.
2. Find the earliest. The cause is usually a change made just before it — a new device, an update, a price import, a printer swap.
3. Stop the bleeding. If it is ongoing, get it stopped before working out the history.
4. Fix forward, then backfill. Correct the configuration, confirm new invoices are accepted, then deal with the affected ones.
5. Document what happened. Dates, cause, fix, and the range of invoices affected. If it is ever asked about, you have the answer.

Anything affecting a material number of invoices deserves a conversation with your tax adviser before you start issuing corrections.

What good tooling gives you

A rejection list you can group by message, filter by device and date, and export. The invoice UUID next to each. A retry that is idempotent. And a device-level view, because rejections are usually one device rather than the whole estate.

That is what Wameed's compliance view provides; see theZATCA page.

Not tax advice — confirm corrections with your adviser or ZATCA.