Odoo ZATCA E-Invoicing: How Phase 2 Integration Works for Saudi Businesses

Odoo ZATCA E-Invoicing: How Phase 2 Integration Works for Saudi Businesses

For many finance and IT leads in the Kingdom, Odoo ZATCA e-invoicing is where an ERP project either earns trust or creates a backlog of rejected invoices. Phase 2 of the Fatoora programme, the integration phase, requires your invoicing system to talk directly to ZATCA: standard tax invoices are cleared before they reach the buyer, and simplified invoices are reported shortly after they are issued. Odoo's Saudi localization is built for this, but it is only as good as the data behind it.

This guide explains what Phase 2 asks of an ERP, how Odoo's Saudi e-invoicing works as Odoo documents it, a practical implementation checklist and the failure points that most often hold projects back. If you need the regulatory background first, start with our FATOORAH Phase 2 compliance guide; if you are still evaluating the platform itself, read our Odoo ERP guide for Saudi businesses.

Table of Contents

• What ZATCA Phase 2 requires, in plain terms
• What an ERP integration has to do
• How Odoo ZATCA e-invoicing works
• Implementation checklist for Odoo and Fatoora integration
• Common failure points and how to fix them
• Configure Odoo, change ERP or add a connector?

What ZATCA Phase 2 requires, in plain terms

ZATCA describes e-invoicing as moving invoices, credit notes and debit notes from paper into a structured electronic exchange between seller and buyer. Phase 1 (generation) required a compliant electronic solution. Phase 2 (integration) adds a live connection to ZATCA's systems and a prescribed invoice format. ZATCA rolls Phase 2 out in waves by taxpayer group and states that it notifies taxpayers of their wave at least six months in advance; check the ZATCA Phase 2 roll-out page for the current wave list rather than relying on second-hand summaries.

In practical terms, a Phase 2 solution must handle the following:

• Two invoice types. A tax invoice, usually B2B or B2G, and a simplified tax invoice, usually B2C. Each has its own mandatory fields.
• Clearance for tax invoices. Each tax invoice, and its related credit and debit notes, is sent to ZATCA in real time. ZATCA validates it and, if it passes, stamps it and returns it. Only then should it be shared with the buyer.
• Reporting for simplified invoices. Simplified invoices and their notes are stamped by your own solution, given to the customer, and reported to the Fatoora platform within 24 hours of issue.
• Structured format. Invoices are generated as XML, or as a PDF/A-3 file with the XML embedded. Submissions through the API use the XML.
• QR code and cryptographic stamp. The stamp proves who issued the document and that it has not changed. The QR code lets anyone run a basic validation with a phone.
• Onboarding with a CSID. Each invoicing unit is registered through the Fatoora portal using a one-time password (OTP) and receives a Cryptographic Stamp Identifier (CSID), which has an expiry date and must be renewed.

What an ERP integration has to do

ZATCA's E-Invoicing Detailed Guidelines set out functions a compliant solution must have and functions it must not have. Translated into ERP requirements, a working integration needs to:

• Build valid XML from your master data. Seller and buyer names, VAT numbers, addresses, tax categories and totals all flow from the ERP into the XML. Bad master data produces bad invoices.
• Keep an unbroken chain. Each invoice carries the hash of the previous one, the invoice counter cannot be reset, and one unit cannot run parallel sequences.
• Route each document correctly. Tax invoices go to clearance; simplified invoices go to reporting. Credit and debit notes follow the type of invoice they adjust.
• Read and act on ZATCA's response. Accepted, accepted with warnings, rejected or not received are four different outcomes, each with a different next step.
• Protect issued documents. Issued invoices cannot be edited or deleted. A mistake is corrected through a credit note and a new invoice, and system logs must be tamper-proof.
• Protect the stamping key and the clock. The private key behind the CSID must not be exportable, and users must not be able to change the system time in a way that falsifies invoice timestamps.
• Archive in the required format. Invoices and notes are stored as XML or PDF/A-3 with embedded XML, on premises in Saudi Arabia or in the cloud in line with VAT and other applicable rules, and must be available to ZATCA on request.

How Odoo ZATCA e-invoicing works

Odoo's Saudi Arabia localization documentation describes a set of modules: the base Saudi accounting package, Saudi Arabia - E-invoicing (l10n_sa_edi) for the Phase 2 API connection, and point-of-sale modules for simplified invoices. Odoo publishes this documentation for several recent versions, and screens, menu names and available modules differ between them. Confirm with your partner which version, edition and hosting model your database runs before planning the work.

As documented for Odoo 19.0, the flow works like this:

• Company and contact data. The company record needs a name of no more than 63 characters, full address details including district, building number and plot identification, an identification scheme such as the Commercial Registration number, the VAT number and SAR as currency. Customer records need equivalent data.
• Three API modes. Sandbox (a shared test environment), Simulation (a company-specific pre-production environment linked to the Fatoora simulation portal) and Production. Odoo warns that once Production is set and an invoice is submitted, you cannot switch back.
• Journal onboarding. Each sales journal is onboarded separately from its ZATCA tab using a six-digit OTP generated in the Fatoora portal. OTPs expire after 60 minutes. Branches can share the parent journal or have their own onboarded journal.
• Submission. After an invoice is confirmed, Odoo sends it to ZATCA, generates a UBL 2.1 XML file and records the response in the invoice chatter. A PDF/A-3 with the embedded XML can be produced when the invoice is sent. Invoices with a business customer go to clearance; B2C sales are reported.
• Credit and debit notes. Each note needs a ZATCA reason, such as a refund or a change to the agreed supply value, and a reference to the original invoice.
• Point of sale. With the simplified e-invoicing module installed, the PoS invoice journal is onboarded and receipts carry the Phase 2 QR code.

Behind the onboarding button sits ZATCA's own process: the unit sends a certificate signing request, receives a compliance CSID, passes compliance checks and then receives a production CSID. Knowing this helps when onboarding fails and the CSR must be regenerated.

Implementation checklist for Odoo and Fatoora integration

Use this sequence for a new rollout or to repair an existing one:

1. Confirm scope. List every legal entity, branch, sales journal and PoS that issues invoices, and confirm your Phase 2 integration date with ZATCA.
2. Clean company data. Check the VAT number, CR number, Arabic and English names and the full national address against official records.
3. Clean customer data. For B2B customers, capture the VAT number or other identifier and a complete address. Capture it at order entry, not at invoicing.
4. Map taxes. Review each tax for its ZATCA category. Odoo requires an exemption reason code on 0% taxes, and its documentation gives specific rules for global discounts, retention and advance payments.
5. Test in sandbox, then simulation. Use a duplicate database for simulation. Invoices sent to the production portal count as real submissions.
6. Run a full test pack. Standard and simplified invoices, credit and debit notes, foreign-currency sales, discounts, exempt and zero-rated lines, advance payments and branch invoices.
7. Onboard production journals. Generate OTPs in the Fatoora production portal, onboard each journal and revoke any unit you no longer use.
8. Set error ownership. Name who reviews warnings and rejections daily, and how quickly they must be resolved.
9. Reconcile. Compare invoice counts in the Fatoora portal with Odoo, especially in the first weeks.
10. Diarise CSID renewal. Record each certificate's expiry date and renew before it lapses.

Common failure points and how to fix them

Two further risks deserve attention. First, clock and time zone settings: ZATCA prohibits inaccurate timestamps, and the 24-hour reporting window depends on correct issue times, so keep servers and PoS devices synchronised. Second, the urge to fix an issued invoice by editing it. Once accepted, an invoice is corrected only through a credit or debit note with a ZATCA reason. ZATCA's guidelines also cover what to do when its servers, your internet connection or a device fails, including notifying ZATCA.

Configure Odoo, change ERP or add a connector?

The choice usually depends on where your invoices are created:

• Configure Odoo's native localization when Odoo already issues all or most of your invoices and runs a supported version. This keeps clearance, accounting and archiving in one system.
• Use a connector or middleware when invoices come from several systems, such as a legacy ERP, a billing platform and a separate PoS, or when an older version cannot be upgraded in time. The trade-off is another system to maintain, monitor and reconcile.
• Move to another ERP only when the wider business case supports it. Phase 2 alone is rarely a reason to replace a system that otherwise works.

Ask for help when your integration date is close and testing has not started, when rejection rates are rising, when you run multi-branch or multi-company setups, or when heavy customisations touch invoice creation. Our Odoo ERP implementation team can help configure and test the Saudi localization, and our tax technology integration services support the link between your systems and your VAT obligations. E-invoicing rules and technical specifications are updated from time to time, so confirm the current requirements with ZATCA or a qualified adviser before go-live.

Frequently Asked Questions

Need a clear plan to bring your Odoo invoicing into line with ZATCA Phase 2? Contact Sokrab Saudi Arabia today.