Dear ZATCA E-Invoicing Technical Support / Developer Community,
We are implementing a Saudi ZATCA Phase 2-compliant e-invoicing system and need an authoritative clarification regarding the invoice lifecycle when a submission fails or is rejected.
We have reviewed the available ZATCA technical documentation and would like to confirm the exact expected behavior from ZATCA’s perspective.
We are intentionally asking this question without assuming whether the correct solution is retrying the same document or creating a replacement document. We would appreciate clarification based on the applicable ZATCA specifications and API behavior.
1. Scenario
Consider the following sequence:
Invoice 1
-
Invoice Number:
INV-001 -
ICV:
1 -
UUID:
UUID-A -
PIH: the correct previous invoice hash according to the invoice sequence
-
The invoice XML is generated, signed and prepared for submission.
The system attempts to submit INV-001 to ZATCA.
However, the submission fails because of a technical problem, for example:
-
Internet connection failure
-
Connection timeout
-
ZATCA server/API temporarily unavailable
-
Connection reset
-
HTTP/network failure
-
Application/server failure before the ZATCA response is persisted
There is no indication that the invoice itself contains a validation error.
The important question is:
If the system does not receive a definitive ZATCA rejection response, should this invoice be considered “Rejected” by the taxpayer’s system?
Or should it remain in a state such as:
Submission Pending / Unknown Submission Result / Technical Failure
until its status can be safely determined?
2. Important distinction: Technical Failure vs Confirmed ZATCA Rejection
We understand that the following situations may be fundamentally different:
A. Technical failure / unknown result
The system sends the invoice but receives no definitive ZATCA response.
Examples:
-
Timeout
-
Network failure
-
Connection lost
-
ZATCA API temporarily unavailable
-
Application crash after sending the request but before storing the response
In this situation, we do not know whether ZATCA received and processed the invoice.
B. Confirmed ZATCA rejection
ZATCA receives and validates the invoice and explicitly returns a rejection response containing validation errors.
Could you please confirm whether ZATCA expects these two situations to be handled differently?
3. Retry of the same document after a technical failure
Suppose INV-001 was generated and signed successfully, but the submission failed because of a network/technical issue and there is no confirmed ZATCA rejection.
Should the taxpayer retry the exact same final electronic document, including:
-
Same Invoice Number
-
Same UUID
-
Same ICV
-
Same PIH
-
Same Invoice Hash
-
Same signed XML
-
Same QR information
-
Same cryptographic signature
rather than generating a new invoice?
If this is correct, could you please confirm explicitly whether the final signed XML should be persisted and reused for retry instead of regenerating and re-signing the invoice?
4. Confirmed ZATCA rejection
Now consider a different situation.
INV-001 is successfully submitted and ZATCA explicitly responds with:
Rejected
together with one or more validation errors.
After fixing the underlying problem, what is the correct ZATCA-compliant procedure?
Specifically:
Is the taxpayer allowed to resubmit the same invoice using the same:
-
Invoice Number
-
UUID
-
ICV
-
PIH
-
Invoice Hash
-
Signed XML
after correcting the XML/data problem?
Or:
Must the rejected document remain as a historical rejected document and a new/corrective electronic document be generated?
We would like ZATCA to clarify this explicitly because we have found different interpretations in third-party implementations.
5. ICV behavior
This is particularly important to us.
Suppose:
INV-001 has:
ICV = 1
and the submission is technically unsuccessful.
The taxpayer then issues:
INV-002
with:
ICV = 2
and INV-002 is successfully submitted.
Later, the taxpayer wants to resolve the earlier unsuccessful submission of INV-001.
What is the correct expected behavior according to ZATCA?
Should the system:
Option A
Retry INV-001 using:
ICV = 1
because the original submission was not confirmed as rejected?
Or:
Option B
Create a new document with a new ICV because INV-002 has already been submitted?
Or is the answer dependent on whether the original submission was technically unsuccessful versus explicitly rejected?
We would appreciate an explicit answer for this scenario.
6. PIH / Invoice Hash chain
We also need clarification regarding the Previous Invoice Hash (PIH).
Assume:
INV-001 → ICV 1
and later:
INV-002 → ICV 2
If INV-001 experienced a technical submission failure but was not confirmed as rejected, how should the PIH relationship be handled?
For example:
Should INV-002 use the hash of the finalized INV-001 document regardless of whether INV-001 was successfully submitted to ZATCA?
Or does ZATCA expect a different treatment?
We are particularly concerned about the following situation:
INV-001
ICV = 1
Submission technically fails
↓
INV-002
ICV = 2
Submission succeeds
↓
Retry INV-001
What should be the correct PIH relationship for the retry of INV-001?
We want to ensure that the invoice hash chain is never broken.
7. UUID behavior
Please also clarify the expected UUID behavior.
If an invoice has already been generated and signed but its submission fails because of a technical/network problem:
Should the retry use the same UUID?
Or should a new UUID be generated for the retry?
Likewise, if a document was explicitly rejected by ZATCA and a replacement/corrective document is required, should the replacement receive:
-
a new UUID,
-
a new ICV,
-
a new Invoice Hash,
-
a new PIH relationship,
while maintaining the appropriate reference to the original rejected document?
8. createReplacement behavior
Our current application has a mechanism called:
createReplacement
When a document is marked as rejected, the application prevents resubmission and displays a message similar to:
“The invoice was previously rejected by ZATCA and is retained as a historical non-editable document. To submit an alternative document, use createReplacement.”
We would like to know whether this is actually the correct interpretation of ZATCA’s requirements.
Most importantly:
Does ZATCA require a replacement electronic document to represent a new accounting transaction?
Our concern is that creating a replacement must not unintentionally duplicate:
-
Sales revenue
-
Output VAT
-
Customer receivable
-
Inventory movement
-
Payment
-
Journal entries
For example, if the original commercial sale is already recorded in the accounting system, creating a replacement electronic document should not automatically create a second sale and duplicate the financial impact.
Therefore, we would appreciate clarification on whether the replacement is fundamentally:
- A new commercial/accounting transaction,
or
- A new/corrected electronic document associated with the original commercial transaction.
9. Accounting impact
We would also appreciate guidance on the relationship between the ZATCA electronic document lifecycle and the underlying commercial/accounting transaction.
Suppose:
Commercial Sale
↓
Invoice INV-001
↓
ZATCA rejection
If a corrected/replacement electronic document is required, should the accounting system:
-
retain the original commercial transaction,
-
avoid posting revenue/VAT/inventory a second time,
-
link the new electronic document to the original transaction,
provided that the commercial transaction itself has not changed?
We want to make sure our implementation does not create duplicate accounting entries merely because the electronic document required correction.
10. Rejection vs replacement vs credit/debit note
Could you also clarify the difference between:
-
Resubmitting the same document after a technical failure
-
Correcting a document that was explicitly rejected by ZATCA
-
Creating a replacement/corrected document
-
Issuing a Credit Note
-
Issuing a Debit Note
Specifically, when should each mechanism be used?
We do not want to use a Credit Note or Debit Note merely to compensate for a technical submission failure if the underlying commercial transaction is unchanged.
11. Accepted with warnings
Please also confirm the expected behavior when ZATCA returns:
Accepted with Warnings
Should the document be treated as successfully cleared/reported and therefore never resubmitted?
If the warning is later determined to require correction, should the correction follow the same mechanism as a rejected document, or is another process required?
12. Unknown result after timeout
Another critical scenario:
The system sends the invoice to ZATCA.
The request reaches the server, but the taxpayer’s application times out before receiving the response.
Therefore, the taxpayer cannot determine whether ZATCA:
-
accepted the invoice,
-
rejected it,
-
or never received it.
What is the officially recommended procedure in this situation?
Specifically:
-
Should the taxpayer retry the same document?
-
Should it generate a new document?
-
Is there an official status/query mechanism that should be used first?
-
How should the taxpayer avoid accidentally submitting the same invoice twice?
If an official API/status-check mechanism exists, please provide the relevant API/documentation reference.
13. Concrete sequence we would like ZATCA to confirm
Could you please provide the correct expected behavior for this exact sequence?
1. Create INV-001
ICV = 1
UUID = A
PIH = X
2. Generate and sign final XML.
3. Submit INV-001.
4. Submission fails because of an Internet/network/timeout problem.
No ZATCA rejection response is received.
5. Create INV-002.
ICV = 2
UUID = B
PIH = ?
6. INV-002 is successfully accepted.
7. The system later attempts to resolve INV-001.
For steps 5–7, please specify:
-
What should the PIH of
INV-002be? -
Should
INV-001retain ICV 1? -
Should
INV-001retain UUID A? -
Should the original signed XML be reused?
-
Can the exact same XML be retried?
-
If a new document is required, what happens to the original ICV/PIH relationship?
-
What should happen if INV-001 was actually rejected rather than technically failed?
-
What should happen to the accounting transaction?
14. Official documentation reference
For each of the above cases, we would greatly appreciate references to the specific official ZATCA documentation, section, and—if applicable—API specification/version that defines the required behavior.
We specifically need authoritative clarification on:
-
ICV
-
PIH
-
Invoice Hash
-
UUID
-
Clearance
-
Rejection
-
Technical failure
-
Retry
-
Unknown submission result
-
Replacement documents
-
Credit/Debit Notes
-
Duplicate submissions
-
Accounting implications
We do not want to implement behavior based on assumptions or third-party interpretations.
Final question
What is the officially correct lifecycle for a ZATCA Phase 2 invoice when submission fails technically versus when ZATCA explicitly rejects the invoice?
In particular, we need to know whether a technically failed submission can be retried using the exact same finalized document and identifiers, and how this differs from a confirmed ZATCA rejection requiring correction or replacement.
Thank you in advance for providing a precise technical answer and, where possible, referencing the exact ZATCA specification/API documentation applicable to the answer.
Best regards,