Odoo 19 ZATCA Phase 2 Troubleshooting Guide

A ZATCA error rarely means that the entire Odoo integration is broken. In many cases, the rejection comes from one incomplete company field, an incorrectly onboarded sales journal, unsuitable customer data, a tax configuration problem, or a mismatch between the testing and production environments.

How ZATCA Phase 2 works in Odoo 19

Odoo 19 provides the Saudi accounting localization and a dedicated e-invoicing integration. The l10n_sa_edi module enables the Phase 2 API connection, while point-of-sale e-invoicing uses the simplified-invoice integration provided by l10n_sa_edi_pos.

The transaction type matters:

• Business-to-business (B2B): a standard tax invoice is submitted through the clearance workflow.
• Business-to-consumer (B2C): a simplified tax invoice is generated with the required QR information and submitted through the reporting workflow.

That distinction affects customer data, document type, validation and the way a rejected transaction should be investigated.

Pre-troubleshooting checklist

Before changing code or reinstalling modules, verify the foundation:

1. The Saudi fiscal localization and required e-invoicing modules are installed.
2. The company name, complete address, country, VAT number and identification fields are accurate.
3. The correct ZATCA API mode is selected: Sandbox, Simulation or Production.
4. Every sales journal used for compliant invoicing has been onboarded in the correct environment.
5. The invoice customer, taxes, products and document type match the real transaction.
6. Arabic invoice requirements and your bilingual document configuration have been reviewed.

Seven common Odoo ZATCA problems and how to diagnose them

1. The journal will not onboard

First confirm that the OTP came from the same environment selected in Odoo. A Simulation OTP should not be used while the database is configured for Production. Verify company identification data before requesting another OTP, and remember that onboarding applies to the journal—not globally to every sales flow.

2. One branch works but another branch fails

Odoo’s official guidance requires each sales journal to be onboarded separately. A new branch, POS or parallel invoicing flow may use a different journal. Check the journal selected by the failed invoice and confirm its ZATCA onboarding status.

3. The invoice is rejected because of company or customer information

Compare the invoice data with the company and contact master records. Check the VAT number, commercial registration or identification scheme, address components, country, city and postal information. For B2B transactions, incomplete buyer tax information can lead to a different result than a correctly classified B2C sale.

4. Tax totals or exemption information fail validation

Review the tax applied to every line, the tax category, zero-rated or exempt treatment and any required exemption reason. Do not “fix” a validation error by changing the tax treatment without finance approval. Correct the accounting configuration and business document together.

5. The invoice is accepted with warnings

A warning is not the same as a rejection. Odoo documents a yellow state for an invoice accepted with warnings. The document may be valid, but the warning should still be investigated and corrected before the same data problem appears across future invoices.

6. The invoice is rejected and Retry keeps failing

Open the invoice chatter and read the complete ZATCA response. Odoo stores the generated UBL XML and response evidence with the invoice. Identify the first meaningful validation failure, correct its source data or configuration, and then use Retry. Repeated retries without changing the underlying data only reproduce the rejection.

7. Point of Sale receipts are not reported correctly

Confirm that the Saudi simplified e-invoicing/POS modules are installed, the POS invoice journal is onboarded, and the customer is assigned when required by your workflow. Test the printed receipt and PDF output, then confirm that the Phase 2 QR information and reporting response are present.

A safer recovery process

1. Preserve evidence: keep the invoice chatter response, XML attachment and a screenshot of the configuration state.
2. Classify the failure: onboarding, master data, tax, document type, journal, certificate/environment or connectivity.
3. Reproduce safely: use Sandbox or a duplicated database in Simulation when the issue can be recreated outside production.
4. Correct the source: fix the company, contact, tax, product, journal or localization configuration—not the generated XML by hand.
5. Validate again: process a controlled invoice and confirm the API response before resuming volume.
6. Monitor the next batch: review warnings and rejections so one configuration issue does not affect many invoices.

When you should escalate the issue

Escalate when the same rejection continues after the source data is corrected, when certificate or onboarding state is unclear, when production invoices are affected across multiple journals, or when custom modules modify invoice totals, taxes, XML generation or posting behavior.

A useful escalation package contains the Odoo version, database environment, invoice type, journal, complete error response, relevant XML attachment, modules involved and the exact steps needed to reproduce the failure. Remove confidential customer data before sharing evidence outside your authorized support team.

Official references

• ZATCA electronic invoice specifications
• ZATCA e-invoicing guidelines library
• Official Odoo 19 Saudi Arabia localization documentation

Reviewed and published by SmartDesk Solution on 22 August 2026. Requirements and software behavior can change; always check the latest official documentation.