Odoo: checking the ZATCA e-invoice XML

The file Mutabiq needs

Mutabiq checks the e-invoice itself: the UBL 2.1 XML generated for each invoice, credit note and debit note under Phase 2 of e-invoicing with the Zakat, Tax and Customs Authority (ZATCA), whether your system generates it or an e-invoicing add-on or integration connected to it does. A PDF with the invoice XML embedded in it (PDF/A-3) works as well. A PDF without that XML, a printout, a spreadsheet export or a screenshot carries nothing Mutabiq can check.

What Odoo documents

• Odoo documents its ZATCA e-invoicing as part of its own Saudi Arabia localization, so where that is what you run, the XML is generated inside Odoo rather than by a separate product (Odoo documentation, Saudi Arabia).
• The documentation reads the seller’s details from the company and the buyer’s from the customer, so a value missing from the XML is usually missing from one of those two records first (Company information).
• It says that “only rejected invoices can be reset to draft and edited on Odoo” (Testing).
• The documentation read for this guide is for Odoo 18.0. Many installations run an earlier version, or a ZATCA module built by an Odoo partner, which may read its values from different places. The XML elements such a module has to write are the same, so the checks below apply to it unchanged.

Where the file usually is

Where the XML is kept depends on how your system is connected to ZATCA, not only on which system it is, and this guide names a screen or menu only where the vendor's own documentation states it, cited and dated. The usual places to look:

• The e-invoicing or ZATCA section of your system, or of the add-on that handles e-invoicing for it, which may list each document with its status and let you view or download its XML.
• The portal of your e-invoicing solution provider, if a provider sends your documents to ZATCA for you: the XML is often kept there beside each document’s clearance or reporting result.
• An export or download of the document after it was cleared or reported, sometimes packaged with the PDF sent to the customer.
• Your provider or implementer. If none of these shows the file, ask for the UBL XML of the document exactly as it was generated for ZATCA.

Check the file as your system generated it. A copy opened and saved again in another program may no longer be the file ZATCA receives.

What to check in the exported XML

• The seller’s address: confirm that cac:AccountingSupplierParty/cac:Party/cac:PostalAddress carries all six elements ZATCA reads: cbc:StreetName, cbc:BuildingNumber, cbc:CityName, cbc:PostalZone, cbc:CitySubdivisionName (the district) and cac:Country/cbc:IdentificationCode. Mutabiq reports a missing one under MTB-BR-KSA-09, at WARNING. The additional number (cbc:PlotIdentification) is no longer among them in ZATCA’s current checker, though it is still part of the National Address.
• The buyer’s address on a standard invoice to a Saudi customer: the same six elements under cac:AccountingCustomerParty, each present and not blank, reported by MTB-BR-KSA-63, at WARNING.
• The seller’s identifier is read from cac:PartyIdentification/cbc:ID with a schemeID attribute. Confirm the attribute is one of CRN, MOM, MLS, SAG, OTH or 700(the 700 number ZATCA’s XML Implementation Standard lists in section 13.3.1, which its current checker accepts); MTB-BR-KSA-08 reports anything else, at WARNING.
• The VAT number is read from cac:PartyTaxScheme/cbc:CompanyID. Confirm it is the 15 digits alone, beginning and ending in 3, with no spaces, dashes or prefix; MTB-BR-KSA-40 reports the seller’s and MTB-BR-KSA-44 the buyer’s.
• The type code and the currency. Confirm cbc:InvoiceTypeCode holds 388, 381 or 383, and that on a domestic invoice cbc:DocumentCurrencyCode and the currencyID attribute on every amount read SAR. MTB-BR-CL-04 reports a document currency code outside ISO 4217.
• Confirm the type code’s name attribute is seven, eight or nine characters — 01 or 02, then one 0 or 1 for each transaction flag, such as 0100000 or 0200000 — and that the export does not pad it or pretty-print the element onto its own line; MTB-STRUCT-01 reports the transaction code.
• Zero-rated and exempt supplies: the reason code is read from cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReasonCode, a property of the VAT breakdown rather than of the line. Confirm every zero-rated and exempt breakdown carries one of the published VATEX-SA- values for its category; MTB-BR-KSA-CL-04 reports an unlisted code, and MTB-BR-KSA-69 a zero-rated breakdown with no code at all, both at WARNING. ZATCA’s current checker asks for the code only, not for the reason text beside it.
• Confirm the document carries a cac:AdditionalDocumentReference whose cbc:ID is ICV and whose cbc:UUID holds the counter as digits only, and that the counter increments across every document issued, credit and debit notes included; MTB-BR-KSA-33 reports a missing counter.
• Confirm the PIH reference beside it carries cac:Attachment/cbc:EmbeddedDocumentBinaryObject with mimeCode="text/plain" and a non-empty base64 value, on the first document of a chain as much as on the rest.
• Confirm you are checking a document from the live connection, not from a test or simulation run: a test document is not the document ZATCA receives later.

What to do with the findings

• Fix the source, not the file. Each finding names an element of the XML, and the value in it came from your system: a setting, a master record such as the company, the customer, the item or the tax code, or the mapping that writes the XML. Correct it there, so the next document is generated right.
• Do not edit the XML by hand and send the edited copy. The file that goes to ZATCA is the one your system generates and signs, and an edited copy is not that file.
• Where the mapping itself is wrong, take the finding to whoever maintains your e-invoicing: the ERP vendor, the add-on or integration provider, or your implementer. The rule id, the element’s path and the rule’s page are what they need to find it.
• A document that has already been cleared or reported is not corrected by sending it again. Ask your accountant or provider how your system corrects it; usually that is a credit or debit note and, where needed, a new document.
• Once the source is fixed, check the next file your system generates.

Sources

• Odoo documentation 18.0, Fiscal localizations, Saudi Arabia

These pages were read on 2026-09-11. Vendor documentation changes.