ZATCA e-invoicing Phase 2: connecting Odoo to ZATCA, step by step

Phase 2 of e-invoicing, the integration phase, links your invoicing system directly to FATOORA, the platform of the Zakat, Tax and Customs Authority (ZATCA). Each invoice now reaches ZATCA electronically, in a set format, instead of only being printed with a QR code. If your company has been notified of its wave, or expects to be soon, this guide explains what changes and how the setup works in Odoo.

What changes in Phase 2

Phase 1, the generation phase, only required issuing invoices electronically, with a QR code on simplified invoices. Phase 2 adds integration with ZATCA:

• A structured format: every invoice is generated as an XML file (UBL 2.1) with a unique identifier (UUID), a cryptographic stamp and a hash that links it to the previous invoice.
• Clearance for standard (B2B) tax invoices: an invoice to another business is sent to ZATCA and cleared before it is shared with the buyer.
• Reporting for simplified (B2C) invoices: invoices to consumers, including point-of-sale receipts, are reported to ZATCA within 24 hours of being issued.
• Credit and debit notes follow the same flow, and each one must reference the original invoice.

Companies join in waves. ZATCA notifies each company of its date, usually at least six months ahead, so there is time to prepare.

Before you start: what to prepare

• A version of Odoo that supports Phase 2: the official Saudi e-invoicing integration is available in recent versions (Odoo 16 and later). On an older version, you need either a third-party module or an upgrade.
• Complete company data: the VAT number, the commercial registration number and the full National Address, including the 4-digit building number, the district and the 5-digit postal code.
• Clean customer data: business customers need a valid VAT number (15 digits, starting and ending with 3) and a complete address. Most rejections come from incomplete customer records.
• Access to the FATOORA portal for the person who will generate the one-time passwords (OTPs) used during onboarding.
• Your invoicing points: list every sales journal, branch and point of sale that issues invoices, because each one is onboarded separately.

Step by step in Odoo

1. Enable the Saudi e-invoicing module and check that the Saudi chart of accounts and taxes are set up correctly.
2. Complete the company record with the VAT number, the identification number and the National Address fields.
3. Start in the simulation environment: set the ZATCA API mode to simulation (pre-production), so you can test without affecting your real submissions.
4. Onboard each sales journal: generate an OTP from the FATOORA portal and enter it on the journal in Odoo. Odoo requests the compliance certificate (CSID) and runs ZATCA's compliance checks automatically.
5. Test real scenarios: a standard invoice, a simplified invoice, a credit note and a debit note. Make sure each one is cleared or reported without errors.
6. Switch to production: change the API mode to production and onboard the journals again with a new OTP. From then on, every validated invoice goes to ZATCA automatically.

Common errors and how to avoid them

• Incomplete addresses: a missing building number, or a postal code that is not 5 digits, leads to rejections. Fix the data before going live.
• Wrong VAT numbers on business customers, or a business customer set up as an individual.
• Credit notes without a reference to the original invoice, or without a reason.
• Editing or deleting validated invoices: in Phase 2, corrections are made with credit or debit notes, never by changing an invoice that was already sent.
• Rounding and tax settings that differ from ZATCA's rules, especially on prices that include VAT.

How we help

We have implemented e-invoicing for companies in food, retail, manufacturing and contracting. We review your data, onboard your journals and points of sale, test every type of document in simulation and train your team before going live. We also stay with you if ZATCA rejects an invoice later.