Saudi E-Invoice XML & QR Code: Technical Specifications Explained

XML Format: UBL 2.1 for Saudi E-Invoices

Saudi Arabia mandates the Universal Business Language (UBL) 2. 1 standard for all electronic invoices.

Saudi Arabia mandates the Universal Business Language (UBL) 2.1 standard for all electronic invoices. This is an international standard (ISO/IEC 19845) that structures invoice data in machine-readable XML.

Key XML Elements

Invoice Header

• <cbc:UBLVersionID> — must be "2.1"
• <cbc:ProfileID> — "reporting:1.0" (B2C) or "clearance:1.0" (B2B)
• <cbc:ID> — unique invoice number
• <cbc:UUID> — globally unique identifier
• <cbc:IssueDate> — YYYY-MM-DD format
• <cbc:IssueTime> — HH:MM:SS format (Saudi Arabia time)
• <cbc:InvoiceTypeCode> — 388 (invoice), 381 (credit note), 383 (debit note)
• <cbc:DocumentCurrencyCode> — SAR (or foreign currency with SAR conversion)

Seller and Buyer Information

The <cac:AccountingSupplierParty> element must include:

• Party name in Arabic
• Street address, building number, city, postal code, district
• VAT registration number (<cbc:CompanyID schemeID="VAT">)
• Commercial Registration number (optional but recommended)

For B2B invoices, the buyer (<cac:AccountingCustomerParty>) must include the same level of detail.

Line Items

Each <cac:InvoiceLine> must contain:

• Line ID (sequential within the invoice)
• Invoiced quantity and unit of measure
• Line extension amount (quantity × unit price)
• Item description
• Price per unit (excluding VAT)
• Tax category and percentage
• Discount (if applicable)

Tax Calculations

The XML must include both line-level and invoice-level tax totals:

• <cac:TaxTotal> with <cbc:TaxAmount> at invoice level
• <cac:TaxSubtotal> per VAT category (standard 15%, zero-rated, exempt)
• Tax amounts must match the mathematical calculation — ZATCA validates rounding

QR Code Specification: TLV Encoding

Saudi e-invoice QR codes use Tag-Length-Value (TLV) encoding — a binary format that packs multiple data fields into a compact QR code.

Saudi e-invoice QR codes use Tag-Length-Value (TLV) encoding — a binary format that packs multiple data fields into a compact QR code.

TLV Fields

The TLV data is base64-encoded and rendered as a QR code. Phase 1 only requires tags 1–5. Phase 2 adds tags 6–8 for cryptographic verification.

Validation Rules

ZATCA applies over 100 validation rules during clearance.

ZATCA applies over 100 validation rules during clearance. The most common rejection reasons:

• VAT calculation mismatch — line items must add up exactly (rounding to 2 decimal places)
• Invalid VAT number — buyer/seller VAT numbers must exist in ZATCA's registry
• Missing mandatory fields — any required XML element omitted triggers rejection
• Incorrect invoice type code — using 388 for a credit note, or vice versa
• Broken hash chain — the previous invoice hash doesn't match

Testing in the ZATCA Sandbox

Before going live, test your implementation against ZATCA's sandbox API. The sandbox validates your XML structure, QR code encoding, and cryptographic stamps without affecting real tax records.

Before going live, test your implementation against ZATCA's sandbox API. The sandbox validates your XML structure, QR code encoding, and cryptographic stamps without affecting real tax records.

For businesses not yet required to integrate via API, Invoicemonk generates Phase 1-compliant invoices with all mandatory fields and SAR formatting. Create a Saudi invoice →