Foodics: 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 Foodics documents

• Phase 2 is activated per branch and per cashier device. Foodics’ activation guide has the branch data entered first — the commercial registration number, the tax registration name, the tax number and the national address of each branch, under Console, Manage, Branches, Edit Branch — and one tax rate of 15% on every taxable item; then an OTP generated in Fatoora under “Onboard New Solution Unit/Device”, one per device, entered on the cashier under “Home > E-Invoice (Zatca)” and activated (Guide for Activating ZATCA Phase 2 (E-Invoice)). Foodics’ own page on the subject says that after activation, new closed and returned orders are sent to ZATCA (ZATCA Phase 2).
• Each device’s activation can be read in the Console: a “ZATCA Activation Status” column under Devices, per cashier device, Active, Inactive or Not Synced (Monitor ZATCA Activation Status from the Console). Each order’s submission can be read there too: an “Invoice Sync Status” column in Orders and a “Zatca Sync Status” section on the order (Status for syncing order invoices with ZATCA).
• The XML Foodics sends is the document ZATCA judges, and the status Foodics shows is ZATCA’s answer to it. Foodics documents no field for a customer’s VAT number on an order and no standard (B2B) invoice flow; what it documents is the simplified invoice of a closed or returned order, reported to ZATCA. A corporate or catering invoice that needs a standard tax invoice is not covered by this guide.

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 Foodics?

Foodics documents a per-order download from the Console, not from the cashier and not through an API. As its changelog describes it, read on 2026-10-15:

1. Open the order in the Console (Orders, then the order’s details page).
2. Use the “Download E-Invoice” button on the Order Details page. The changelog says the file is in a ZATCA-readable XML format and that the button is available for invoices synced with ZATCA with the status Success or Failure (ZATCA E-Invoice Export (KSA Only)).
3. To find the orders worth checking, Foodics documents a report under Reports, Business Reports, “ZATCA Invoice List”, filtered by Order Reference, Branch, Invoice Sync Status (Success, Success with Warning, Failure), Error/Warning Code and Order Business Date, with a View pop-up that shows ZATCA’s error and warning codes and messages (New Zatca Report (Zatca Invoice Listing)).

So a day’s sample for one device is a set of orders from that branch and that business date, downloaded one order at a time; Foodics documents no bulk export. A “Failure” is the order to download first: ZATCA’s code in the report says which rule refused it, and Mutabiq’s report on the same XML says which element and what to check, before the order is resubmitted. The index of Foodics’ developer documentation lists no section for the e-invoice XML, the QR code or the ZATCA status (Foodics developer documentation), so no way to fetch the files by API is documented there.

Menus change; Mutabiq has not verified these screens itself. If yours differs, or if the button is not there for an order you need, ask Foodics support for the order’s ZATCA XML exactly as it was sent. If no file can be had, Mutabiq has nothing to check: what it checks is the file.

What to check in the exported XML

• The seller’s data on every branch: Foodics writes the invoice from the branch record, so a branch left with an empty tax number or a free-text address fails on that branch alone. Confirm the seller’s cac:PartyTaxScheme/cbc:CompanyID is the 15 digits alone, beginning and ending in 3 (MTB-BR-KSA-40 reports an empty one), that cbc:StreetName under the seller’s cac:PostalAddress is present (MTB-BR-KSA-09), and that the commercial registration number is written as cac:PartyIdentification/cbc:ID with schemeID CRN (MTB-BR-KSA-08).
• The simplified-invoice shape: confirm cbc:InvoiceTypeCode is 388 on a sale and 381 on a return, with a name attribute beginning 02 (MTB-STRUCT-01 reports the attribute), and that the QR document reference is present with a non-empty base64 payload (MTB-BR-KSA-27).
• The rate: Foodics asks for one 15% rate on every taxable item. Confirm every standard-rated breakdown carries cbc:Percent of 15; MTB-BR-KSA-84 reports any other rate under category S.
• The counter and the hash per device: each cashier device is its own solution unit, so its ICV runs on its own and its PIH is the hash of that device’s previous document. Confirm both document references are present (MTB-BR-KSA-33 and MTB-BR-KSA-61); a day’s orders from one device should show the counter climbing by one.
• Returns: a returned order goes out as a credit note. Confirm it carries a reason in cac:PaymentMeans/cbc:InstructionNote (MTB-BR-KSA-17) and the original order’s invoice number in cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID (MTB-BR-KSA-56).

None of these is a setting the branch can change on the cashier: a finding on a Foodics XML goes to whoever administers your Console, and from there to Foodics support with the rule id and the element’s path.

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

• Foodics help centre: Guide for Activating ZATCA Phase 2 (E-Invoice)
• Foodics: ZATCA Phase 2
• Foodics changelog: ZATCA E-Invoice Export (KSA Only)
• Foodics changelog: New Zatca Report (Zatca Invoice Listing)
• Foodics changelog: Monitor ZATCA Activation Status from the Console (KSA)
• Foodics changelog: Status for syncing order invoices with ZATCA (KSA clients)
• Foodics developer documentation

All pages were read on 2026-10-15; the changelog entries carry relative dates on the page and are quoted as they stood that day. Vendor documentation changes.