ZATCA e-invoicing: a rent invoice is not a PDF any more

Before electronic invoicing, a rent invoice in Saudi Arabia was whatever the managing agent produced: a PDF from the property system, a spreadsheet printed to paper, occasionally a book of pre-printed forms filled in by hand. The document was the invoice. What the system stored was a record of it.

ZATCA reversed that. The invoice is now a structured file with a prescribed format, a cryptographic stamp and a place in an ordered chain — and the authority either clears it before the customer may be given it, or receives a copy within a day of issue. The PDF still exists, but it has been demoted to a rendering. The invoice is the XML.

For a property business this lands harder than it does for a shop, because rent is billed in bulk. A retailer issues invoices one at a time as customers arrive. A managing agent issues eight hundred on the first of the quarter, in a single run, and every one of them now has an external dependency in the middle of it.

Phases, waves and the revenue thresholds that decide when a taxpayer is brought in are set by ZATCA and have moved as the rollout has progressed. This is written for people designing billing software, not as tax advice — confirm your own wave, your own obligations and the current technical specification with the authority.

Generation and integration are two separate obligations

The regime arrived in two stages, and they ask for different things. The first — generation, in force since December 2021 — says the invoice must be produced by compliant electronic software. That alone ended handwritten invoices, invoices typed into a word processor, and invoices edited after the fact, and it required a QR code on simplified invoices.

The second — integration, from January 2023 and phased in waves by taxpayer revenue — connects the software to ZATCA. Invoices become XML in a prescribed structure, carry a cryptographic stamp and a UUID, and are chained: each one embeds a hash of the one before it, so removing or reordering an invoice is detectable rather than merely against the rules.

Which of the two paths an invoice takes depends on what kind of invoice it is. A standard tax invoice — the business-to-business case — must be cleared: submitted to ZATCA and stamped by the authority before it is handed to the customer. A simplified invoice, the business-to-consumer case, is issued immediately and reported afterwards, within a day.

That distinction is not a technicality for a property manager. A commercial lease is billed to a registered business, so the taxable rent invoices a managing agent issues are largely standard invoices — which means clearance, which means the invoice is not valid until a remote service has answered.

Clearance puts a remote service inside the billing run

A billing run that issues invoices locally and writes them to a database is a loop that either succeeds or rolls back. A billing run that must clear each invoice with an external authority is a distributed workflow, and it fails in ways a loop does not: timeouts, partial success, a response that arrives after the request was abandoned, a rejection on invoice four hundred and seven.

The shape that survives is an invoice with an explicit lifecycle — drafted, submitted, cleared, rejected — persisted before anything is sent, retried idempotently, and never re-submitted under a fresh identity because the first attempt appeared to fail. A duplicate cleared invoice is considerably harder to unwind than a missing one.

The chaining makes it stricter still. Because each invoice carries the hash of its predecessor, the sequence is genuinely serial: invoices cannot be cleared in parallel and reconciled afterwards, and a gap cannot be filled in later. Concurrency has to be resolved before the chain, not inside it.

• Allocate the number and persist the invoice before the first call, not after a successful response.
• Make submission idempotent on a stable key, so a retry cannot produce a second cleared invoice.
• Serialise the chain per issuing unit; parallelise across units instead of within one.
• Treat a rejection as a state on the invoice, not an exception that aborts the run.
• Keep the returned stamp and cleared XML — they are the invoice, not a receipt for it.

The QR code is TLV, and Arabic is where naive code breaks

The QR code carries a base64-encoded TLV structure: for each field, a tag byte, a length, then the value. The Phase 1 fields are the seller name, the VAT registration number, the timestamp, the invoice total including VAT, and the VAT amount. Integration adds the hash of the invoice, the cryptographic stamp and the public key.

The defect almost everyone ships at least once is in the length. It is the length of the value in BYTES once encoded as UTF-8, not the number of characters in the string. In English the two are the same number, so the code passes every test written against an English seller name. An Arabic seller name is roughly two bytes per letter, so the declared length is about half the real one, and every scanner reads the field as truncated and the ones after it as garbage.

In a market where the seller name on the invoice is legitimately Arabic — and where Arabic is required on the tax invoice in the first place — this is not an edge case. It is the default case, discovered late because the test fixture was called Acme Trading.

Test the QR with an Arabic seller name, by scanning it, before shipping. A unit test that asserts the base64 matches a fixture generated by the same buggy function will agree with itself indefinitely.

A cleared invoice cannot be edited, only answered

Once an invoice has been cleared, the authority has it. Editing the stored record to fix a wrong amount, a wrong period or a wrong tenant now puts the system into open disagreement with ZATCA, and the cryptographic stamp is what makes that disagreement provable rather than arguable.

Corrections are separate documents: a credit note or a debit note that references the original invoice, states the reason, and goes through the same clearance. This is the same discipline good accounting already asks for, but e-invoicing removes the option of ignoring it. A system with an edit button on an issued invoice is not merely untidy in Saudi Arabia; it is producing records that contradict the ones the authority holds.

The same logic governs storage. The cleared XML and its stamp are the legal record and have to be retained and retrievable for the statutory period, in a form that does not depend on the current version of the rendering template. An invoice reprinted in three years must show what was actually issued.

What it means for a rent ledger specifically

Rent is recurring, which means invoices are generated on a schedule rather than in response to an event, and often in advance of the period they cover. The date of supply, the invoice date and the due date are three different dates, and a system that collapses them into one will be wrong about at least one of them at a quarter boundary.

The portfolio is also usually mixed. Residential leases are an exempt supply and do not produce a tax invoice at all, while commercial leases in the same building do — so the billing run cannot assume every line it touches is in scope. Forcing a tax invoice for exempt residential rent is as wrong as omitting one for a commercial lease, and it is the more common mistake because it looks like consistency.

And the exemption is narrower than it first appears. Management fees, agency commission and most service charges billed to an owner are taxable services at the standard rate, so even an agent whose entire portfolio is residential is issuing tax invoices — to the owners rather than to the tenants.

• Classification follows the unit and its use, resolved once, not chosen per invoice.
• Supply date, invoice date and due date stored separately and derived from the lease.
• Fees and commissions to owners treated as taxable services in their own right.
• Rate stored on the line as issued, so a reprint after a rate change still shows what was charged.