ZATCA Rejected Invoices & Warnings: The Most Common Errors and How to Fix Them
Your system is connected to ZATCA, but invoices keep coming back rejected or with warnings. Here are the errors we see most often in Saudi businesses, what each one means, and how to fix the cause instead of the symptom.
Connecting to ZATCA is only the first step. After go-live, every invoice is checked by ZATCA's Fatoora platform. Invoices with errors are rejected, and invoices with smaller problems are accepted with warnings. Both need attention: a rejected standard invoice cannot legally be shared with your customer, and warnings that are ignored today can turn into errors after the next rule update.
Most rejections are not caused by a broken integration. They come from the data that goes into the invoice: a customer record with an incomplete address, a discount that breaks the totals, a device restored from an old backup. That is good news, because it means the cause can be found and fixed once instead of patched invoice by invoice.
This guide covers the errors we fix most often for Saudi businesses on ERPNext, Odoo, point-of-sale systems and custom software, and a simple process to stop them from coming back.
Rejected vs. accepted with warnings: what is the difference?
ZATCA validates every invoice against its business rules. The response tells you whether the invoice passed, passed with warnings, or failed. Errors mean the invoice is not valid. Warnings mean the invoice was accepted, but something in it does not follow best practice or an upcoming rule.
Standard tax invoices (B2B) go through clearance: ZATCA must approve them before you send them to the buyer. Simplified tax invoices (B2C) go through reporting: you give the invoice to the customer, then report it to ZATCA within 24 hours. A rejection blocks a standard invoice immediately, and leaves a simplified invoice unreported until it is corrected.
- Error: the invoice is rejected and must be corrected and resubmitted.
- Warning: the invoice is accepted, but the cause should still be fixed.
- Standard (B2B) invoices: cleared by ZATCA before they reach the buyer.
- Simplified (B2C) invoices: reported to ZATCA within 24 hours.
- The response lists each failed rule with a code and message. Keep it, as it is your starting point.
Error 1: VAT number and buyer details
This is the most common cause of rejected B2B invoices. A Saudi VAT registration number has 15 digits and starts and ends with 3. Typing mistakes, spaces, or a commercial registration number entered in the VAT field are rejected straight away.
Standard invoices also need the buyer's national address. Missing building numbers, wrong postal codes or an empty district field are enough to block clearance.
- Check the buyer's VAT number: 15 digits, starting and ending with 3.
- Complete the national address: street, building number (4 digits), postal code (5 digits), district and city.
- Fix the customer record in your system, not the single invoice, so the next invoice is correct too.
- Check your own seller details as well, including the address on your VAT certificate.
Error 2: totals, discounts and rounding
ZATCA recalculates your invoice. Line amounts, discounts, VAT and the document totals must match each other exactly. Systems that round each line differently from the total, or apply a discount after VAT, produce invoices that look fine on paper but fail validation.
- Line net amount must equal quantity times price, minus line discounts.
- VAT is calculated on the amount after discounts.
- Invoice-level discounts and charges (such as delivery fees) need the correct VAT category.
- Use consistent rounding (two decimals) for lines and totals.
- Zero-rated or exempt lines need the right VAT category and reason.
Error 3: broken invoice hash chain and counter
Each invoice from a device carries the hash of the previous invoice and a running counter. This links all invoices from that device into a chain. If the chain breaks, ZATCA flags it.
We see this after a server or POS is restored from a backup, when two devices share one certificate, when an invoice is deleted from the database, or when invoices are sent out of order after a network outage.
- Never delete issued invoices. Cancel them with a credit note instead.
- Give every branch, POS terminal or server its own onboarded device.
- After a restore, check the last submitted invoice before issuing new ones.
- Queue invoices during outages and send them in order once you are back online.
Error 4: certificates and onboarding
Your system signs every invoice with a certificate (CSID) issued during onboarding. Certificates expire, can be revoked, and are tied to one environment. An expired certificate, or a test certificate used in production, causes every invoice to fail at once.
Renewal needs a new one-time password (OTP) from the Fatoora portal. Many businesses only find out when invoices suddenly stop clearing, often on a busy day.
- Track certificate expiry dates and renew before they expire.
- Make sure the production certificate is used for live invoices.
- Keep access to the Fatoora portal with the right person in your company.
- Re-onboard devices properly when you change servers or POS hardware.
Error 5: credit notes, debit notes and returns
Credit and debit notes must reference the original invoice and include the reason for the change. Returns entered as a negative invoice, or credit notes without a reference, are rejected.
- Always link the credit note to the original invoice number.
- Add a clear reason, such as a return, a price correction or a cancellation.
- Use the same customer and VAT treatment as the original invoice.
- Do not issue negative invoices to handle returns.
A 5-step process to fix ZATCA errors for good
Fixing rejected invoices one by one wastes time and leaves the cause in place. This is the process we follow with our clients.
- Collect: export every rejected invoice and warning with ZATCA's response codes.
- Group: sort them by rule. Usually three or four causes explain most of the problems.
- Fix at the source: correct customer records, tax settings, rounding or device setup.
- Resubmit: correct and resend the affected invoices in the right order.
- Monitor: check every invoice automatically, so new errors are caught on the same day.
How CODEXTERS helps
Our team has connected and supported hundreds of ZATCA integrations across ERPNext, Odoo, POS and custom systems. We review your rejected invoices and warnings, find the root causes, fix them in your system, renew certificates, and monitor every invoice afterwards so problems are fixed before they grow.
You keep the software you already use. Message us on WhatsApp at +966 57 343 2877 for a free 15-minute check, in English or Arabic.
Frequently asked questions
Why was my ZATCA invoice rejected?+
The most common causes are an invalid buyer VAT number or incomplete national address, totals that do not add up after discounts or rounding, a broken invoice hash chain, an expired or wrong certificate, and credit notes without a reference to the original invoice. The ZATCA response lists the exact rule that failed.
Can I ignore ZATCA warnings if the invoice was accepted?+
It is not a good idea. Warnings mean the invoice does not fully follow the rules. ZATCA updates its rules over time, and some warnings can become errors. Fixing the cause now avoids sudden rejections later.
Can I send a rejected standard invoice to my customer?+
No. Standard (B2B) invoices must be cleared by ZATCA before they are shared with the buyer. Correct the error and submit the invoice again.
What should I do if all my invoices suddenly fail?+
When every invoice fails at the same time, the cause is usually the certificate (expired, revoked or the wrong environment) or a connection problem. Check the certificate first, then renew it with a new OTP from the Fatoora portal if needed.
Should I delete a rejected invoice and issue a new one?+
Do not delete issued invoices, as this breaks the invoice hash chain. Correct and resubmit the invoice, or cancel it with a credit note, depending on the situation.
Can you fix errors in an integration built by someone else?+
Yes. We regularly fix integrations built by other providers or in-house teams, on ERPNext, Odoo, POS and custom systems. We start with a free 15-minute check on WhatsApp.
Topics covered
Related reading
Need help building this?
CODEXTERS designs and builds software across ERP and ERPNext, ZATCA e-invoicing compliance, AI and data platforms, SaaS products, and startup MVPs — for companies of every size.