ZATCA e-invoicing in Odoo works through the Saudi Arabia localization. The l10n_sa_edi module turns each Odoo invoice into a UBL 2.1 XML e-invoice, signs it, adds the QR code and sends it to ZATCA’s Fatoora platform: B2B tax invoices for clearance, and B2C simplified invoices for reporting within 24 hours. You connect each sales journal with a one-time password from the Fatoora portal.
Summary answer: ZATCA’s e-invoicing rules (Fatoora) apply to every VAT-registered business resident in Saudi Arabia. Phase 1, in force since 4 December 2021, requires invoices to be generated and stored by a compliant electronic system, with a QR code on simplified invoices. Phase 2 adds integration with ZATCA. It started on 1 January 2023 and is rolled out in waves, and ZATCA notifies each wave at least six months before its deadline. The latest wave we could verify, Wave 25 (announced 24 July 2026), covers taxpayers with VAT-subject revenue above SAR 187,500 in any year from 2022 to 2025, with integration due by 1 February 2027. In Phase 2, standard tax invoices (B2B) must be cleared by ZATCA before they reach the buyer, and simplified invoices (B2C) must be reported within 24 hours. Odoo handles both through its Saudi e-invoicing modules for invoicing and Point of Sale. Each journal is onboarded with a Fatoora OTP, tested in simulation, then moved to production.
What ZATCA e-invoicing is and who must comply
E-invoicing, which ZATCA brands as Fatoora, replaces paper invoices, credit notes and debit notes with structured electronic documents. According to ZATCA’s e-invoicing page and its FAQ, the rules apply to all persons subject to VAT in Saudi Arabia and to any party that issues tax invoices on behalf of a VAT-registered supplier. Non-resident taxable persons are excluded.
A few points that often confuse finance teams:
- A scanned PDF is not an e-invoice. ZATCA’s guideline says a paper invoice converted by copying or scanning does not count.
- Some transactions need no e-invoice. ZATCA’s FAQ lists exempt supplies, imports of goods and supplies under the reverse charge mechanism.
- Individual VAT taxpayers are covered too, not only companies.
Phase 1 vs Phase 2, and how the waves work
| Point | Phase 1: Generation | Phase 2: Integration |
|---|---|---|
| Start date | 4 December 2021, for all taxpayers in scope | From 1 January 2023, in waves |
| What changes | Invoices issued and stored by a compliant electronic system; no manual invoices | System connects to ZATCA’s Fatoora platform through APIs |
| File format | No specific format required | XML (UBL 2.1), or PDF/A-3 with the XML embedded |
| Security features | Optional | Cryptographic stamp, invoice hash, UUID, invoice counter |
| QR code | Mandatory on simplified invoices | Mandatory, in ZATCA’s Phase 2 format |
| Sharing with ZATCA | Not required | Clearance (B2B) or reporting (B2C) |
How wave thresholds work
ZATCA selects each Phase 2 wave by revenue subject to VAT in named reference years. If your VAT-subject revenue exceeded the threshold in any of those years, you are in the wave. Each new wave lowers the threshold, so more small businesses are brought in over time. ZATCA then notifies the targeted taxpayers directly, at least six months before their integration date. Until you are notified, Phase 2 is not mandatory, although ZATCA encourages early compliance.
| Wave (announcement date) | Revenue threshold | Reference years | Integrate by |
|---|---|---|---|
| Wave 1 (24 June 2022) | Above SAR 3 billion | 2021 | From 1 January 2023 |
| Wave 22 (21 March 2025) | Above SAR 1 million | 2022, 2023 or 2024 | 31 December 2025 |
| Wave 24 (26 September 2025) | Above SAR 375,000 | 2022, 2023 or 2024 | 30 June 2026 |
| Wave 25 (24 July 2026) | Above SAR 187,500 | 2022, 2023, 2024 or 2025 | 1 February 2027 |
At the time of writing (November 2026), ZATCA’s Wave 25 announcement is the latest we could verify. Later waves may follow, so check the news section of zatca.gov.sa and the notification sent to your registered email and mobile number.
Standard vs simplified invoices: clearance and reporting
| Point | Standard tax invoice | Simplified tax invoice |
|---|---|---|
| Typical use | B2B and B2G sales | B2C sales and POS receipts; B2B sales below SAR 1,000 may also use it |
| ZATCA process | Clearance: ZATCA validates the invoice and adds its stamp before you share it | Reporting: you give the invoice to the buyer, then report the XML within 24 hours |
| Who stamps it | ZATCA, at clearance | Your system, using the certificate (CSID) ZATCA issued to it |
| QR code | Generated by ZATCA at clearance; your system prints it | Generated by your system |
| How Odoo decides | Business customer with full company details | Individual or walk-in customer |
What a Phase 2 e-invoice must contain
- XML in UBL 2.1 format. Odoo generates it on submission and can produce a PDF/A-3 with the XML embedded when you send the invoice.
- A UUID, a unique identifier stored in the XML.
- A cryptographic stamp that proves which onboarded system issued the document.
- A hash chain. Each document carries the hash of the previous one (the “Previous Invoice Hash”) and a counter that cannot be reset. This is why gaps or deleted invoices are not allowed.
- A Phase 2 QR code, which buyers can check with ZATCA’s VAT app.
- Arabic text. The XML tags are in English, but the invoice data a person reads must be in Arabic. A second language such as English can appear alongside.
How to onboard Odoo with ZATCA, step by step
Odoo’s Saudi Arabia localization documentation sets out the process. These are the modules involved:
| Module | Technical name | Role |
|---|---|---|
| Saudi Arabia – Accounting | l10n_sa | Chart of accounts, 15% VAT and Phase 1 QR code |
| Saudi Arabia – E-invoicing | l10n_sa_edi | Phase 2 API integration with ZATCA |
| Saudi Arabia – E-invoicing (Simplified) | l10n_sa_edi_pos | E-invoicing from Point of Sale |
| Saudi Arabia – Point of Sale | l10n_sa_pos | Compliance fields for POS receipts |
- Complete the company record. Company name (63 characters at most), full address including district, building number and plot identification, an identification scheme such as the Commercial Registration Number, the VAT number, and SAR as the currency. Apply the same care to customer records.
- Test in Sandbox. Set the ZATCA API mode to Sandbox, a shared test environment with a pre-filled OTP, and confirm that test invoices return “Action Successful”.
- Test in Simulation (Pre-Production). Duplicate your live database, set the mode to Simulation, and onboard each sales journal with a 6-digit OTP from the Fatoora simulation portal. Test B2B, B2C, credit notes and foreign customers. Simulation invoices are not legally valid.
- Generate the production OTP. Log in to the Fatoora portal (fatoora.zatca.gov.sa) with your ZATCA taxpayer credentials and request an OTP. OTPs expire after 60 minutes.
- Onboard each sales journal in production. In the journal’s ZATCA tab, click Onboard and enter the OTP. Behind this button, Odoo generates a private key and a certificate signing request (CSR), obtains a compliance certificate, runs ZATCA’s compliance checks and then receives the production certificate (CSID).
- Issue and monitor. Confirm an invoice, click Process now and read ZATCA’s response in the chatter.
Once you switch to Production and submit an invoice, you cannot go back to Sandbox or Simulation. If you retire a journal, revoke its CSID in the Fatoora portal under View List of Solutions and Devices.
Branches and multiple companies
For a branch, Odoo asks you to use the parent company’s VAT number with the branch’s own Commercial Registration Number in the identification scheme field. Branches can share the parent’s sales journal or each onboard their own. ZATCA also allows a separate invoice sequence per branch, as long as each sequence is clear and continuous, and every device issuing invoices under one VAT number must be registered. Groups with several legal entities onboard each company’s journals under that company’s VAT number.
Common ZATCA rejection errors in Odoo and how to fix them
Odoo colors each response: green for accepted, yellow for accepted with warnings, and red for rejected. A rejected invoice is not legally valid. Fix the cause and click Retry; Odoo resubmits it with its own counter and hash.
| Response or message | Likely cause | Fix |
|---|---|---|
| 400 Rejected, missing mandatory field | Incomplete company or customer data, such as address parts or buyer ID | Complete the record, then Retry |
| 202 warning BR-KSA-F-13 (Other Seller/Buyer ID invalid) | Wrong identification scheme or number on the contact | Correct the CR number or other ID on the contact |
| 401 Unauthorized | Certificate or secret problem | Check the journal’s credentials; onboard again with a new OTP if needed |
| OTP rejected during onboarding | OTP older than 60 minutes, or taken from the wrong portal | Generate a new OTP from the portal that matches the API mode |
| “The journal is stuck” | Invoices still pending submission when you try to re-onboard | Submit the pending invoices first, then onboard |
| Tax errors on discounted invoices | Global discount line without VAT | Put the 15% tax on the global discount line |
| Credit note rejected | No ZATCA reason or no reference to the original invoice | Select a ZATCA reason and reference the original invoice number |
| 429, 500, 503 or 504 | ZATCA busy or unavailable; invoice not received | Resend; nothing in your data needs to change |
Fix warnings too: ZATCA says they may become rejections, and repeated warnings can lead to an audit.
Credit notes, debit notes and POS receipts
Credit and debit notes
Invoices cannot be cancelled in Phase 2. To correct one, you issue a credit or debit note, which follows the type of the original invoice: notes against standard invoices are cleared, and notes against simplified invoices are reported. ZATCA requires every note to reference the original invoice, and a range can be used when one note covers several invoices. In Odoo, choose one of the approved reasons in the ZATCA Reason field:
- Cancellation or suspension of the supply, in whole or in part
- An essential change to the supply that changes the VAT due
- An amendment to the pre-agreed supply value
- A refund of goods or services
- A change in the seller’s or buyer’s information
If the note is not linked to an invoice in Odoo, enter the original invoice number in the Customer Reference field.
Point of Sale
With the l10n_sa_edi_pos module installed, you onboard the POS default Invoices journal the same way as any sales journal. Cashiers then assign a customer to each order before payment; a generic walk-in customer record works for anonymous sales. Each receipt is processed as a simplified e-invoice, reported to ZATCA, and prints the Phase 2 QR code. Turn on the Gulf Cooperation Council format in the POS receipt settings to add Arabic.
If a till loses its connection, the 24-hour reporting clock still runs. ZATCA’s guideline says that if you cannot report within 24 hours, you should notify ZATCA through its dedicated form and report as soon as the connection returns. Our guide to POS systems in Saudi Arabia covers offline mode and hardware.
Penalties for non-compliance
ZATCA has the power to levy penalties for e-invoicing breaches. In its announcement of 16 November 2021, made for Phase 1, ZATCA stated that:
- Not issuing electronic invoices starts with a fine of SAR 5,000.
- Deleting or amending e-invoices after issuance starts with a fine of SAR 10,000.
- Leaving the QR code off a simplified invoice, leaving the buyer’s VAT number off a tax invoice, or failing to tell ZATCA about a malfunction that stops invoicing starts with a warning.
Fines then depend on the type of violation and how often it is repeated. Penalty rules and relief programs change, so check the current position on zatca.gov.sa or with your tax adviser before you rely on any figure.
ZATCA readiness checklist and setup time
| Step | What to do | Done when |
|---|---|---|
| 1. Confirm your wave | Check ZATCA’s notification and wave announcements | You have a written integration date |
| 2. Check your Odoo version | Confirm you run a supported version with the Saudi modules | l10n_sa_edi is installed |
| 3. Clean master data | Company, branch and customer VAT numbers, CR numbers and full addresses | No blank ZATCA fields on active customers |
| 4. Review taxes and documents | Tax codes, exemption reasons, discounts, credit note reasons, Arabic layout | A sample of each document type prints correctly |
| 5. Get Fatoora access | Confirm who holds the taxpayer portal login | A named person can generate OTPs |
| 6. Test in simulation | Onboard journals on a copy of your database and run every scenario | All test documents return green |
| 7. Go live | Switch to Production and onboard every sales and POS journal | First live invoices cleared or reported |
| 8. Monitor | Review rejected and warning invoices daily for the first weeks | No open red or yellow invoices |
How long setup takes
Data quality and testing take most of the time. Typical ranges (indicative):
- Existing Odoo user, clean data, one or two journals: about 1 to 3 weeks.
- Several branches, POS outlets or messy customer data: about 3 to 6 weeks.
- New Odoo implementation with ZATCA included: 4 to 8 weeks for a focused rollout, longer for multi-company groups.
Start at least three months before your deadline so there is room to fix data and test. If you are on an old Odoo version, plan an upgrade first; our Odoo upgrade guide explains the steps. For budgets, see our Odoo implementation cost guide for Saudi Arabia (SAR).
How OzonLayer helps with ZATCA in Odoo
OzonLayer IT Services is an official Odoo Silver Partner with three Odoo 18 certified consultants, 11 customer references published on odoo.com and 50+ clients served, with our office in Riyadh. For a real project, read how we delivered ZATCA integration for an industrial steel company.
We configure the Saudi localization, clean your data and onboard your journals as part of our Odoo implementation services in Saudi Arabia. After go-live, Odoo support in Saudi Arabia covers rejected invoices, certificate issues, new branches and new journals. For VAT returns and bank reconciliation, read about Odoo accounting software in Saudi Arabia, and see all our Odoo services in Saudi Arabia.
ملخص بالعربية
الفوترة الإلكترونية (فاتورة) نظام أقرّته هيئة الزكاة والضريبة والجمارك لتحويل إصدار الفواتير والإشعارات الدائنة والمدينة من الشكل الورقي إلى عملية إلكترونية. ويسري على جميع الأشخاص المقيمين الخاضعين لضريبة القيمة المضافة في المملكة العربية السعودية، ويُستثنى منه غير المقيمين. بدأت المرحلة الأولى (مرحلة الإصدار والحفظ) في 4 ديسمبر 2021، وبدأت المرحلة الثانية (مرحلة الربط والتكامل) في 1 يناير 2023 على شكل موجات، وتُخطر الهيئة المكلفين المستهدفين في كل موجة قبل ستة أشهر على الأقل من موعد الربط. وتشمل الموجة الخامسة والعشرون، التي أُعلن عنها في 24 يوليو 2026، المكلفين الذين تجاوزت إيراداتهم الخاضعة للضريبة 187,500 ريال في أيٍّ من الأعوام 2022 إلى 2025، على أن يتم الربط في موعد أقصاه 1 فبراير 2027.
في المرحلة الثانية تُرسل الفاتورة الضريبية (بين المنشآت) إلى الهيئة للتحقق منها واعتمادها قبل مشاركتها مع المشتري، بينما تُسلَّم الفاتورة الضريبية المبسطة (للمستهلكين) إلى العميل ثم يُبلَّغ عنها خلال 24 ساعة من إصدارها. ويجب أن تصدر الفاتورة بصيغة XML وفق معيار UBL 2.1، أو بصيغة PDF/A-3 مع ملف XML مضمَّن، وأن تتضمن معرّفاً فريداً (UUID) وختماً تشفيرياً وقيمة تجزئة الفاتورة السابقة ورمز الاستجابة السريعة، وأن تكون بياناتها باللغة العربية مع جواز إضافة لغة أخرى.
يدعم نظام أودو هذه المتطلبات من خلال وحدات التوطين السعودي، ولا سيما وحدة الفوترة الإلكترونية للفواتير ووحدة نقاط البيع. ويُربط كل دفتر يومية للمبيعات بشكل منفصل باستخدام رمز تحقق لمرة واحدة من منصة فاتورة، بعد الاختبار في بيئة المحاكاة ثم الانتقال إلى بيئة الإنتاج. ننصح بالبدء قبل موعدكم بثلاثة أشهر على الأقل، وبمتابعة إعلانات الهيئة على موقعها الرسمي باستمرار. احجز استشارة مجانية مع فريقنا.
Not sure which wave you are in, or why invoices keep coming back red? Book a free consultation and we will review your Odoo setup against ZATCA’s requirements, or call +966 56 434 5818.
Frequently asked questions
Does Odoo support ZATCA Phase 2 e-invoicing?
Yes. Odoo's Saudi Arabia localization includes the Saudi Arabia – E-invoicing module (l10n_sa_edi), which connects sales journals to ZATCA's Fatoora platform. It generates UBL 2.1 XML, signs invoices, adds the Phase 2 QR code, sends standard invoices for clearance and reports simplified invoices. A separate module (l10n_sa_edi_pos) does the same for Point of Sale receipts.
How do I know which ZATCA wave my business is in?
ZATCA selects each wave by VAT-subject revenue in named reference years and notifies the targeted taxpayers directly, at least six months before their integration date. Check the notification sent to your registered email and mobile number and the wave announcements on zatca.gov.sa. The latest we could verify is Wave 25, announced on 24 July 2026, with a 1 February 2027 deadline.
What is the difference between clearance and reporting?
Clearance applies to standard tax invoices, usually B2B. ZATCA validates the invoice and adds its stamp before you share it with the buyer. Reporting applies to simplified tax invoices, usually B2C. You give the invoice to the customer first and then send the XML to ZATCA within 24 hours of issue.
Where do I get the OTP to onboard Odoo with ZATCA?
Log in to the Fatoora portal with your ZATCA taxpayer credentials and request an OTP for each solution you want to connect. Use the simulation portal for pre-production testing and the production portal for live use. Each OTP expires after 60 minutes, and every Odoo sales journal, including the POS invoices journal, is onboarded separately.
Why does ZATCA reject my Odoo invoices?
Most rejections come from incomplete or wrong master data, such as missing address parts, a wrong identification number or a missing VAT number. Other causes include a global discount line without the 15% tax and credit notes without a ZATCA reason or invoice reference. Odoo shows the error in the invoice chatter; correct the data and click Retry.
Can I cancel an invoice after it has been sent to ZATCA?
No. Phase 2 invoices cannot be cancelled or deleted. To correct a cleared or reported invoice, issue a credit or debit note with an approved ZATCA reason and a reference to the original invoice. If ZATCA rejected the invoice, fix the error and resubmit it. Odoo keeps the XML and PDF permanently attached to each invoice.
How long does it take to set up ZATCA e-invoicing in Odoo?
For an existing Odoo user with clean data and one or two journals, it typically takes about 1 to 3 weeks, including simulation testing. Several branches, POS outlets or poor customer data push this to about 3 to 6 weeks. A new Odoo implementation with ZATCA included usually takes 4 to 8 weeks for a focused rollout. Start at least three months before your deadline.
What are the penalties for not complying with ZATCA e-invoicing?
In its November 2021 announcement, ZATCA said not issuing e-invoices starts with a SAR 5,000 fine, and deleting or amending e-invoices after issue starts with a SAR 10,000 fine. Missing QR codes, missing buyer VAT numbers and failing to report system malfunctions start with a warning. Fines rise with repetition, so check zatca.gov.sa for current rules.
