ZATCA invoice rejected reasons and how to fix common errors
ZATCA rejects an e-invoice when it fails a required validation check. Common areas to investigate include the seller's VAT number, address fields, invoice calculations, document hashes and signing certificates. The response from Fatoora identifies the checks that failed so you can correct the cause.
Understanding ZATCA rejection messages
When your store sends an invoice to Fatoora, ZATCA checks the XML against its published requirements. The response can have three outcomes.
| Outcome | What it means | What you should do |
|---|---|---|
| Accepted | The document passed validation without warnings. | Keep the invoice and ZATCA response. |
| Accepted with warnings | The document was accepted, but one or more checks raised warnings. | Investigate the warnings and correct the cause for future invoices. |
| Rejected | At least one validation error prevented acceptance. | Correct the cause and follow the appropriate resubmission process. |
An accepted invoice with warnings should not be submitted again. ZATCA's technical guidelines say to investigate warnings promptly because repeated noncompliance may lead to further action.
A rejection requires different handling. ZATCA's guidance says a corrected document must be generated with its own invoice counter and previous invoice hash. The rejected document's original counter and hash must remain unchanged.
Source: ZATCA Detailed Technical Guidelines, section 4.3 and section 7 (Business FAQs)
The rules below are documented validation causes. They are grouped by the part of the invoice you need to inspect, rather than ranked by how frequently they occur.
Seller details errors
The seller VAT number is missing or invalid
Rules: BR-KSA-39 and BR-KSA-40.
BR-KSA-39 requires the invoice to contain the seller's VAT registration number or the seller group's VAT registration number. BR-KSA-40 checks the format.
The VAT number must:
- Contain exactly 15 digits.
- Begin with 3.
- End with 3.
A missing number, incorrect length or wrong first or last digit can produce a validation message.
Check the VAT number stored in your invoicing settings against your registered details. Correct any typing mistakes before generating another document.
In Raseedo, open WooCommerce > ZATCA E-Invoicing > Seller details to check the number. Source: ZATCA XML Implementation Standard, BR-KSA-39 and BR-KSA-40 ZATCA staff also explained BR-KSA-39 in the Fatoora Developer Community.
The seller address is incomplete
Rules: BR-KSA-09, BR-KSA-37 and BR-KSA-66. BR-KSA-09 requires the seller address to contain a street name, building number, postal code, city, district and country code.
The other rules check specific formats:
- BR-KSA-37 requires a four-digit building number.
- BR-KSA-66 requires a five-digit seller postal code.
For example, a seller address that contains a city but has no district does not satisfy BR-KSA-09.
Compare your stored seller information with your registered National Address. Check that the address fields used in the XML contain the required details.
Source: ZATCA XML Implementation Standard, seller address rules
The commercial registration identification is incorrect
Rule: BR-KSA-08.
ZATCA requires the seller identification field to use an allowed identification scheme. A commercial registration number uses the scheme code CRN.
The rule also restricts the identification value to alphanumeric characters and requires the seller identification to appear only once.
Check the commercial registration number and its identification scheme in the generated XML. If your business has multiple commercial registrations, ZATCA's standard says to use the registration of the branch issuing the tax invoice.
Source: ZATCA XML Implementation Standard, BR-KSA-08
Invoice content and VAT calculation errors
Invoice totals do not match
Rules: BR-CO-10, BR-CO-14, BR-CO-15 and BR-CO-17. ZATCA checks whether the invoice's calculated totals agree with its individual amounts.
These rules cover different calculations:
| Rule | What ZATCA checks |
|---|---|
| BR-CO-10 | The sum of invoice line net amounts matches the document's line net total. |
| BR-CO-14 | The invoice VAT total matches the sum of the VAT category tax amounts. |
| BR-CO-15 | The total including VAT equals the amount excluding VAT plus VAT. |
| BR-CO-17 | Each VAT category tax amount matches its taxable amount multiplied by the applicable rate, rounded to two decimals. |
A mismatch may come from how discounts, charges or VAT amounts were calculated in the XML.
Compare the affected invoice lines with the document totals. Check how the invoicing software has treated discounts and tax amounts.
For a WooCommerce order, compare the order's stored amounts with those in the generated XML. If the figures differ, investigate the invoice generation process before creating a replacement.
Source: ZATCA XML Implementation Standard, BR-CO rules
The VAT category is missing or incorrect
Rules: BR-CO-04, BR-KSA-18, BR-KSA-23, BR-KSA-24 and BR-KSA-69.
Every invoice line needs a VAT category. ZATCA defines these category codes:
| Code | VAT category |
|---|---|
| S | Standard rated |
| Z | Zero rated |
| E | Exempt from VAT |
| O | Not subject to VAT |
BR-KSA-18 restricts category values to these codes.
Other checks apply to the reason for the VAT treatment:
- BR-KSA-23 requires an exemption reason code for an exempt VAT breakdown.
- BR-KSA-24 requires an exception reason code for a VAT breakdown that is not subject to VAT.
- BR-KSA-69 requires an exception reason code for a zero-rated VAT breakdown.
Check the tax classification of the affected item. Correct the category or required reason using the appropriate tax treatment for that sale.
Do not change a category merely to make the validation message disappear. The invoice needs to reflect the transaction's correct VAT treatment.
Source: ZATCA XML Implementation Standard, VAT category rules
VAT amounts contain too many decimal places
Rules: BR-DEC-13, BR-DEC-14 and BR-KSA-DEC-03. ZATCA limits the number of decimal places in several invoice amount fields.
BR-DEC-13 covers the invoice VAT total. BR-DEC-14 covers the total including VAT. BR-KSA-DEC-03 covers the VAT amount at invoice line level. These fields permit a maximum of two decimal places.
Check whether the invoice generator is writing unrounded calculation results into the XML.
The correction belongs in the calculation or XML generation process. Keep the underlying transaction amounts consistent with the applicable VAT calculation rules.
Source: ZATCA XML Implementation Standard, decimal rules
A credit note has no reference or reason
Rules: BR-KSA-17 and BR-KSA-56.
A credit note must contain the reason for issuing it. It must also reference the preceding invoice.
BR-KSA-17 covers the reason. BR-KSA-56 requires the billing reference ID for credit and debit notes.
If a refund produces a credit note without the original invoice reference, inspect the information used to build that document.
Raseedo generates credit notes for WooCommerce refunds. Each credit note references the original invoice and carries the refund reason.
Source: ZATCA XML Implementation Standard, credit note rules
Invoice chain and signing errors
The previous invoice hash is missing or incorrectly encoded
Rules: BR-KSA-26 and BR-KSA-61. BR-KSA-61 requires the previous invoice hash, known as PIH, to exist.
BR-KSA-26 specifies how that hash is calculated and encoded. It uses SHA-256 and Base64 encoding, with defined XML elements excluded from the hash calculation.
Each invoice refers to the preceding generated document. This creates a chain that can be checked for changes.
If you receive this message, inspect the invoice generator's hashing process and the previous document reference. The first invoice uses the specific initial hash defined in ZATCA's standard.
Do not manually replace the hash with an arbitrary value.
Raseedo creates documents one at a time and records the previous invoice hash. This prevents simultaneous WooCommerce checkouts from changing the chain out of order.
Source: ZATCA XML Implementation Standard, BR-KSA-26 and BR-KSA-61
The invoice counter is missing or malformed
Rules: BR-KSA-33 and BR-KSA-34.
Every invoice must have an invoice counter value, called ICV. BR-KSA-34 requires that value to contain digits only.
Check whether the document contains the counter in the expected XML field.
ZATCA's technical guidelines also state that an invoice counter must not be reused. A replacement document gets its own counter, including when the earlier document was rejected.
Raseedo assigns the counter when creating each document and maintains the invoice chain.
Sources:
The signing certificate is invalid or the signature is missing
Rule: BR-KSA-60. Certificate validation is also covered in ZATCA's technical guidelines.
BR-KSA-60 requires a cryptographic stamp on simplified tax invoices and their associated notes. ZATCA states that documents signed with invalid certificates are rejected. Check whether onboarding was completed and the store has a valid production certificate associated with its VAT registration.
Raseedo obtains the certificate during onboarding. If the site's AUTH_KEY or SECURE_AUTH_KEY changes, you need to onboard again because the stored certificate and key cannot be decrypted using the new keys. Previously issued invoices are unaffected.
Sources:
- ZATCA XML Implementation Standard, BR-KSA-60
- ZATCA Detailed Technical Guidelines, certificate handling
Reporting time and date problems
A simplified invoice is reported late
Simplified tax invoices must be reported to ZATCA within 24 hours of the transaction.
This is a reporting deadline. A document that misses the deadline should not automatically be treated as having the same validation error as a malformed XML invoice.
Check the document's issue time and its submission status. Investigate network interruptions or ZATCA service problems if the document remained pending.
Raseedo sends simplified invoices through Action Scheduler in the background. It retries network failures and ZATCA outages for hours within the reporting window.
Source: ZATCA Detailed Technical Guidelines, section 4.3.1
The invoice issue date is in the future
Rule: BR-KSA-04. ZATCA requires the document issue date to be no later than the current date.
If this rule appears, check the date written into the XML. Investigate the store's date and time settings and the invoice generation process.
The issue date should reflect the document's correct date. Correct the underlying problem before generating another document.
Source: ZATCA XML Implementation Standard, BR-KSA-04
Checking rejected invoices in Raseedo
Raseedo keeps the signed XML and ZATCA response on your own WordPress site.
To investigate a problem:
- Open WooCommerce > ZATCA E-Invoicing.
- Select the E-invoices tab.
- Find the affected document and check its status.
- Read the rejection reasons returned by ZATCA.
- Identify the relevant seller detail, invoice calculation or technical problem.
- Correct the underlying cause before following the appropriate process for a rejected document.
Raseedo also adds an order note when ZATCA rejects an invoice. Network failures and outages are retried automatically, while rejection reasons remain available for review.
If a certificate is approaching expiry, Site Health warns you 30 days beforehand. You can renew it by onboarding again with a new one-time password (OTP).
For setup instructions and further guidance, visit the Raseedo documentation.
Sources
Questions
Can I resubmit an invoice rejected by ZATCA?
Yes, after correcting the cause of the rejection. ZATCA's technical guidelines require the replacement to be generated as a new document with its own invoice counter and the appropriate previous invoice hash. Keep the rejected document unchanged. An invoice accepted with warnings should not be resubmitted merely because warnings were returned.
Does a ZATCA warning mean my invoice was rejected?
No. ZATCA distinguishes accepted documents with warnings from rejected documents. A warning means the document was accepted despite a validation issue. A rejection means at least one error prevented acceptance. You should investigate warnings and correct their causes for later invoices. The response status tells you which outcome applies.
Where can I see ZATCA rejection reasons in WooCommerce?
With Raseedo, open WooCommerce > ZATCA E-Invoicing > E-invoices. The tab displays rejection reasons returned by ZATCA. The affected WooCommerce order also receives an order note. Raseedo stores the signed XML and ZATCA response on your site so you can review the document and the reported problem.