Invoices and documents
UBL XML
UBL XML is the structured data file, written in the UBL 2.1 format, that every Phase 2 e-invoice carries alongside its QR code and cryptographic stamp. It holds the seller, buyer, lines and VAT amounts in a form that ZATCA's systems read automatically.
What it means
Behind the invoice your customer sees there is a second version made for machines. Under Phase 2 that version is an XML file laid out in the UBL 2.1 format, which gives every item a fixed place: seller, buyer, each invoice line, the VAT on it and the total. Because the layout is agreed in advance, ZATCA's systems can read any invoice the same way.
You will never write this file by hand. Your invoicing system builds it each time you issue an invoice, then adds the cryptographic stamp, the QR code, the UUID, the invoice counter value and the hash of the previous invoice. What it cannot do is fix a missing detail: if a buyer's VAT number or a line's VAT category is blank on screen, the file is incomplete too.
Picture a wholesaler invoicing a supermarket. The clerk fills in the usual invoice screen and presses issue without seeing any technical detail; behind the screen the system produces the XML and sends it to ZATCA for clearance. If you also want a copy people can read, a PDF/A-3 file can carry the XML inside it, so one document serves both the customer and the system.
In practice
- Ask your software provider to confirm it creates UBL 2.1 XML for Phase 2.
- Fill in buyer, line and VAT details completely before pressing issue.
- Archive the XML together with any PDF copy of each invoice.
- Issue sample invoices in ZATCA's simulation environment and check they are accepted.
Questions about UBL XML
Do I have to create or edit a UBL XML file myself?
No. Your invoicing system creates the file from the details you enter when you issue an invoice, so your part is entering complete, correct details and choosing software that supports Phase 2. If something on an invoice turns out to be wrong, the correction is a credit note or debit note that references the original invoice.
Is the XML the same thing as the PDF I send to my customer?
No. The XML is the data file that ZATCA's systems read, while a PDF is the readable copy for people. A PDF/A-3 file can embed the XML, which lets a single document carry both the human-readable invoice and its data. Ask your provider what your system sends to customers.
Issue correct invoices without the guesswork
Try Fatooraz free for 90 days in ZATCA’s simulation environment. No credit card needed.