Noqta
writing/blog/2026/05
● BlogMay 16, 2026·6 min read

Odoo + ZATCA Wave 24: Every Fatoora Gotcha We Hit on Real Saudi Rollouts

Wave 24 hits 30 June 2026 for SAR 375k-750k Saudi SMEs. Here are the five Odoo + Fatoora gotchas that actually bite — plus a 10-point pre-flight checklist.

Anis Marrouchi
·EN · FR · AR

Odoo + ZATCA Wave 24: Every Fatoora Gotcha We Hit on Real Saudi Rollouts

If your Saudi business turns over between SAR 375,000 and SAR 750,000 and you run Odoo, you have roughly six weeks to be live on ZATCA Phase 2.

The Wave 24 cut-off is 30 June 2026. Wave 23 (SAR 750k-1M bracket) already passed on 31 March 2026 — so the regulator is in enforcement mode, not onboarding mode. Miss it and the penalties stack fast: SAR 5,000 minimum, up to SAR 50,000 per violation, plus the operational pain of having every B2B sales invoice rejected on submission.

We have run several Odoo + ZATCA Phase 2 integrations in Riyadh, Jeddah, and Dammam over the last 18 months. The same five things bite every single time. This article is the brief we wish someone had given us before our first rollout.

For the regulatory primer, see our complete ZATCA Fatoora e-invoicing guide for 2026. This piece assumes you already know what Phase 2 is — and zooms in on the Odoo-specific landmines.

Why Odoo + ZATCA Is Genuinely Non-Trivial

Saudi Arabia is the #2 Odoo market in the world by partner count — around 204 active partners, behind only the US (~250) — out of 170,000+ global Odoo customers. That density exists for a reason: Odoo fits the Saudi mid-market well (Arabic RTL, multi-company, manufacturing + retail + services in one stack, reasonable per-user pricing versus SAP).

But ZATCA Phase 2 was not designed with Odoo's data model in mind. The friction shows up in three places:

  1. Fatoora portal architecture. ZATCA's Fatoora portal is the regulator's onboarding interface. You request a Cryptographic Stamp Identifier (CSID) per sales journal, then activate the device for either simulation or production. The clearance and reporting flows are XML-over-API with strict UBL 2.1 schema validation — there is no manual override.
  2. Per-journal device. Each Odoo sales journal (POS, online store, B2B services, manufacturing finished-goods sales, etc.) needs its own ZATCA device in the portal. Multi-company Saudi groups can end up onboarding 8-15 devices in a single Odoo instance.
  3. Mandatory simulation phase. ZATCA requires you to run the integration end-to-end on the simulation environment, generate test invoices, and only then promote to production. The promotion itself is a one-way door — more on that below.

Add Arabic + Hijri reporting, GOSI-compliant payroll, and integrations with mada / Apple Pay / STC Pay, and a "simple ZATCA module install" turns into a six-week project.

The Five Gotchas That Actually Bite

These are ordered by how often they have cost us a re-deploy. They map directly to the FAQ section at the bottom — bookmark them.

1. The 2-Minute OTP Expiry During Device Onboarding

When you onboard a sales journal device through the Fatoora portal, ZATCA emails (or SMS-es) an OTP that expires in 120 seconds. You must enter it inside Odoo's ZATCA wizard before it expires.

In practice this means: the finance lead with Fatoora portal access and the Odoo admin must be physically together during onboarding (or on a live call with screen share). Trying to do it async — "I'll send you the OTP on WhatsApp" — has failed for us more than once because of message delivery delay alone.

Workaround: pre-stage the Odoo wizard up to the OTP prompt, then request the OTP. You buy yourself the full 120 seconds.

2. The One-Way Sandbox → Production Switch

ZATCA's environment switch is irreversible. Once an Odoo journal's device is promoted from simulation to production, you cannot move it back. If your production XML schema validation fails on the first real invoice — for example because your VAT registration number was entered with a stray space, or your buyer's address field is missing the required streetName UBL tag — you cannot quietly retry from sandbox. You have to escalate through ZATCA support to deactivate and re-onboard, which has taken us 3-7 business days in the past.

Mitigation: generate at least 50-100 representative invoices on simulation (B2B, B2C, credit notes, debit notes, foreign-currency, free items) and confirm every single one passes clearance before flipping the switch. The simulation environment behaves identically to production for validation — use it.

3. Multi-Company KSA Setups Multiply Device Count

Saudi business groups frequently run multiple legal entities in a single Odoo instance — a holding company, a retail arm, a contracting arm, a real-estate entity. Each entity has its own VAT registration. Each VAT registration needs its own ZATCA Fatoora onboarding. Each Odoo sales journal inside that entity needs its own device.

We have seen a single Odoo instance need 14 devices onboarded across 4 companies and their POS / online / B2B journals. That is 14 OTP windows, 14 CSIDs to store securely, and 14 production-switch decisions. Budget time for it — and document the per-device CSID storage location before you start, not after.

4. Wrong Simulation-Phase Trigger = Fines on Test Invoices

This one is mean. The Fatoora portal expects you to activate the simulation portal at a specific stage in your onboarding — after sandbox testing, before production go-live. If your Odoo team accidentally configures the production endpoint while the device is still in simulation mode (or vice versa), some test invoices can be flagged as live submissions on the wrong device profile — and non-compliant live submissions carry fines.

[verify] We have seen one client receive a warning notice for this exact misconfiguration; ZATCA waived the fine after we produced the integration logs proving intent, but the policy is at the inspector's discretion. Treat simulation-mode activation as a formal change-control gate: one person flips it, the change is logged in your project tracker, and no production-marked transactions hit the API until after the gate.

5. Arabic / Hijri Reporting + GOSI Payroll Layer

ZATCA Phase 2 itself does not mandate Hijri — Gregorian dates are accepted on the XML invoice. But your Saudi finance team will expect monthly and quarterly reports in Hijri, and your GOSI payroll module must compute contributions on Hijri payroll cycles. Odoo's stock localization (l10n_sa, l10n_sa_edi, l10n_sa_hr_payroll) covers the basics but routinely needs custom report templates — and the Hijri/Gregorian conversion edge cases (Ramadan-month length, year-end straddle) bite at month-close.

This is not a Wave 24 blocker per se, but it will be the second-week-post-go-live escalation — plan for it now.

The 10-Point Pre-Flight Checklist

Copy-paste this into your project tracker. We use it for every Saudi Odoo rollout:

  1. Confirm VAT registration is active and matches the exact spelling on the Saudi commercial registration (CR).
  2. Inventory all sales journals that will issue invoices: POS, online store, B2B services, intercompany, projects, manufacturing finished goods. Each = one ZATCA device.
  3. Install / upgrade Odoo l10n_sa_edi to the version matching your Odoo major (17 or 19). Check the module's changelog for any breaking changes since your last upgrade.
  4. Verify buyer master data: every B2B customer record must have VAT number, full legal name in Arabic + English, and a UBL-compliant address (city, postal code, street, building number).
  5. Set up Fatoora portal accounts for each legal entity. Test login with each account before you need the OTP.
  6. Onboard all devices in sandbox first. Stress-test with credit notes, foreign-currency invoices, and item-level VAT exemptions.
  7. Run 50-100 simulation invoices through the portal. Capture and review every clearance response XML.
  8. Lock CSID storage: every CSID is a secret. Use Odoo's encrypted parameter store or an external secret manager — not a shared Google Sheet.
  9. Schedule the production switch off-peak. Fridays are bad (weekend in KSA); pick a Tuesday or Wednesday morning so you have full ZATCA support availability if something breaks.
  10. Train two finance users on reading clearance failure responses. The error codes are not Odoo-side — they come from ZATCA — and your team needs to triage them without escalating every one to IT.

The Architecture Pattern Noqta Recommends

We deploy ZATCA Phase 2 on Odoo in three named environments, with a deliberate promotion gate at each boundary:

[1] Sandbox          [2] Simulation         [3] Production
(Odoo dev DB)    →   (Odoo staging DB)  →   (Odoo prod DB)
+ ZATCA sandbox      + ZATCA simulation     + ZATCA production
- can re-init        - can re-init          - ONE-WAY door
  unlimited            unlimited

Gate 1 → 2: all sales journals tested with smoke-test invoices, all clearance XML schemas validated, all CSIDs successfully issued in sandbox.

Gate 2 → 3: 50+ representative invoices cleared in simulation, finance team has signed off on Arabic/English UBL output, secrets are in production secret manager (not in Odoo's ir.config_parameter plain-text), and a rollback runbook exists — even though full rollback is not possible, a partial rollback (disable specific journals via Odoo without flipping the ZATCA device back) is what gives you operational safety.

Pair this with an honest e-invoicing readiness audit before kickoff. The audit framework is written for the Tunisian El Fatoora context, but the structure — data quality, master-data hygiene, journal inventory, escalation paths — maps cleanly onto ZATCA.

A Note on Odoo Security

Worth saying because trust matters in finance integrations: Odoo's CVE footprint is unusually low — about 53 published CVEs across the entire vendor since 2017 (compared with hundreds for comparable ERPs). The most recent material one is CVE-2024-36259 — an authenticated information-disclosure flaw in the Odoo 17 mail module, fixed in subsequent maintenance releases.

Two implications:

  • If you are still on Odoo 16 or an unpatched Odoo 17 minor, upgrade before you onboard ZATCA. You do not want to be patching the underlying ERP during your Wave 24 cutover.
  • Most Odoo security advisories are gated behind an active Enterprise subscription. If you run Community Edition, factor in either upgrading to Enterprise or building your own CVE-tracking process — and budget for one hour per month of dedicated patching review.

FAQ

Q1: When exactly is ZATCA Wave 24 due? 30 June 2026, for businesses with annual VAT-taxable turnover between SAR 375,000 and SAR 750,000. Wave 23 (SAR 750k-1M) deadline was 31 March 2026 and is now in enforcement.

Q2: Can I extend the Fatoora OTP beyond 2 minutes? No. The OTP expires in 120 seconds and there is no way to extend it. Pre-stage the Odoo onboarding wizard right up to the OTP prompt before you request the code, and you will have the full window.

Q3: We promoted our Odoo journal to production by mistake — can we revert? Not directly. The sandbox-to-production switch is one-way. You will need to open a ZATCA support ticket to deactivate the device, then re-onboard. Typical turnaround in our experience is 3-7 business days, so do not promote until you are certain.

Q4: We run 4 Saudi companies in one Odoo instance — does each one need separate onboarding? Yes. Each legal entity has its own VAT registration and needs its own Fatoora portal account, its own set of CSIDs, and per-sales-journal device onboarding. A 4-company setup with 3 sales journals per company means 12 devices to onboard.

Q5: Does ZATCA require Hijri calendar reporting? No — ZATCA accepts Gregorian dates on the XML invoice. But your Saudi finance team will expect internal management reports in Hijri, and GOSI payroll computes on Hijri cycles. Plan custom Odoo report templates for this on day one, not month two.

Need a Hand on Wave 24?

With six weeks to the deadline, the calendar is tight. If you want a Saudi-Odoo specialist to pressure-test your Wave 24 plan, identify which of the five gotchas you are exposed to, and scope a realistic delivery, book a 30-minute discovery call with our team. We will tell you honestly whether you can hit 30 June or whether you need a fallback plan.

Authoritative sources