Qoyod: checking the ZATCA e-invoice XML

Product names identify the systems only. Mutabiq is independent of their vendors and is not affiliated with or endorsed by any of them.

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 Qoyod documents

Qoyod describes the e-invoices it produces for ZATCA as UBL/XML, with a QR code added to every invoice, so the XML is generated inside Qoyod itself (Qoyod, e-invoicing product page).
It documents checks that run on an invoice as it is entered, and says in its own FAQ that they do not cover every requirement of the Authority and do not replace a final review. A check at entry and a check on the XML are different things: what ZATCA reads is the file built from those fields, which is what Mutabiq checks (Qoyod, checks before submission and FAQ).
The same FAQ says a rejected invoice cannot be edited and resent as it is: the correction is a credit note and a new invoice (Frequently asked questions).

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.

Where do I get the XML file in Qoyod?

Qoyod documents the path in its knowledge base (When the XML invoice export option appears; the Arabic page: توضيح شروط ظهور خيار إصدار وحفظ الفواتير بصيغة XML). As Qoyod documents it, read on 2026-10-14:

Confirm the Phase 2 link with the Authority is active: Settings, then Electronic Linking.
Go to Sales, then Sales Invoices, and click View beside the invoice.
Scroll down to the Download XML Format option.

Qoyod says the option appears only once the link with the Authority is active, and that the invoice must carry all the data the link requires; the page does not say whether a simplified invoice differs. Its release note of 2026-08-23 adds a Download XML button on the document view page for an establishment on Phase 1 of e-invoicing, for tax invoices, credit notes and debit notes that are approved or paid in full or in part, earlier documents included (E-Invoicing Updates: XML Download). Its release note of 2026-05-24 says the PDF Qoyod generates for a business customer with Phase 2 enabled carries the XML inside it (PDF/A-3), which Mutabiq reads as well (XML File Embedded Inside PDF).

Menus change; Mutabiq has not verified these screens itself. If yours differs, ask Qoyod support for the invoice’s XML, or for a PDF/A-3 that carries it.

What to check in the exported XML

The VAT numbers: confirm the seller’s and the buyer’s cac:PartyTaxScheme/cbc:CompanyID are each the 15 digits alone, beginning and ending in 3. A number that has fifteen digits but the wrong first or last one is still refused; MTB-BR-KSA-40 reports the seller’s number and MTB-BR-KSA-44 the buyer’s.
The issue date: confirm cbc:IssueDate is not later than the day you check, and check the time zone of whatever stamps it: a server ahead of the Kingdom stamps tomorrow’s date late in the evening. MTB-BR-KSA-04 reports a date in the future.
Zero-rated and exempt supplies: the reason code is read from cac:TaxSubtotal/cac:TaxCategory/cbc:TaxExemptionReasonCode on the VAT breakdown, not from the line. Confirm every breakdown coded Z or E carries one of the published VATEX-SA- values with no space in it; MTB-BR-KSA-CL-04 reports the code. A breakdown coded Z or E with no code at all, or an empty one, is reported by MTB-BR-KSA-69 and MTB-BR-KSA-23, both warnings in ZATCA’s current checker.
The buyer’s address: on a standard invoice to a Saudi customer, ZATCA reads six elements under cac:AccountingCustomerParty/cac:Party/cac:PostalAddress: cbc:StreetName, cbc:BuildingNumber, cbc:CityName, cbc:PostalZone, cbc:CitySubdivisionName (the district) and cac:Country/cbc:IdentificationCode. Confirm all six are present and non-empty; MTB-BR-KSA-63 reports a missing one, at WARNING.
The seller’s identifier is read from a seller cac:PartyIdentification/cbc:ID with a schemeID attribute. Confirm the attribute is one of CRN, MOM, MLS, SAG, OTH or 700; MTB-BR-KSA-08 reports anything else, at WARNING. The customer’s identifier on a government or business invoice is the buyer’s equivalent, with a longer list that includes NAT, TIN and CRN, reported by MTB-BR-KSA-14.
Confirm cbc:InvoiceTypeCode holds 388, 381 or 383 and that its name attribute is seven, eight or nine characters, beginning 01 on a tax invoice and 02 on a simplified one, with each remaining position 0 or 1; MTB-STRUCT-01 reports the attribute.
Confirm the ICV and PIH document references are present, that the counter in the first is digits only and increments across every document, and that the hash in the second is a non-empty base64 value declared text/plain.
On a simplified invoice, confirm the QR document reference carries a non-empty base64 payload and that the payload’s seller name, VAT number, timestamp, total and VAT amount match the XML around it.

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

The first two pages were read on 2026-09-11; the knowledge-base article and the two release notes on 2026-10-14. Vendor documentation changes.

Rules to read

The rule pages this guide links, in the order they appear above. Each one quotes the published clause, says what Mutabiq reports, and names what to check in your e-invoicing mapping.

Check an invoice

Check a sample invoice in the browser