ZATCA's Phase 2 "Integration" doesn't add one e-invoicing flow to your ERP — it adds two, running side by side. A B2B standard invoice must be signed with your CSID and cleared by ZATCA's Fatoora platform in real time before it reaches the buyer. A B2C simplified invoice is stamped locally at the point of sale and reported to ZATCA within 24 hours after issue. Same system, different XML sign points, different failure modes. This guide covers the split, the CSID and hash chain that hold it together, and how it lands in ERPNext.
Coming from the Indian e-invoicing model?
If you already run India's GST e-invoicing IRP round-trip, ZATCA's B2B clearance will feel familiar — but the B2C reporting flow and the sequential hash chain are new. Read the two together; the clearance mental model transfers, the details don't.
The trap in ZATCA Phase 2 is treating it as one integration — because the moment a B2B invoice slips into the B2C path, it goes to the buyer without clearance, and it is not a valid invoice. I am Manoj, ERPNext and Frappe implementation lead at Mith Tech in Bengaluru, and the clearance-versus-reporting split is the design decision that makes or breaks a Saudi ERPNext rollout.
Are you in scope yet?
Phase 2 rolls out in waves, each capturing smaller taxpayers than the last. Establish which wave names your business before anything else — the deadline is fixed once you're notified.
Enter your highest annual VAT-taxable revenue across 2022-2024 to see whether you fall within the current ZATCA Phase 2 wave and by when you must integrate.
Taxable revenue above SAR 375,000 in 2022, 2023 or 2024 falls within Wave 24 (announced 26 Sep 2025), with compliance between 1 April and 30 June 2026. If you have not already been notified in an earlier wave, treat this as your window — ZATCA gives about six months' notice per wave and thresholds keep dropping.
Wave 24 threshold (SAR 375,000; comply by 30 Jun 2026) as of 2026-07-31. Waves and thresholds move — check the official ZATCA announcement for the wave that names your business.
Six months is not long for a Phase 2 build
ZATCA gives roughly six months' notice per wave, and Phase 2 is not a config toggle — it is CSID onboarding, UBL 2.1 XML generation, the clearance/reporting split, QR rendering, and the hash chain. Wave 24 has already dropped the threshold to SAR 375,000, the lowest to date. If your revenue is anywhere near it, start the ERPNext work now rather than when the notification lands.
The two flows, and why the split matters
The heart of Phase 2 is that a single ERP must run two fundamentally different invoicing processes, chosen per transaction:
Toggle between a B2B and a B2C invoice to see the sign point, the ZATCA step, the timing, and the failure mode for each Phase 2 flow.
Two flows in the same ERP: B2B clears in real time before delivery; B2C reports within 24h after issue. Both use UBL 2.1. Confirm current field-level requirements on the ZATCA (Fatoora) portal.
B2B is clearance: the invoice is signed with your CSID, transmitted to the Fatoora clearance API, cryptographically stamped by ZATCA, and only then delivered to the buyer. Real-time, before delivery. If the clearance API is unreachable or your CSID is invalid, the invoice cannot be issued — your billing is coupled to ZATCA's uptime.
B2C is reporting: the simplified invoice is stamped locally at the point of sale, handed to the customer immediately, and reported to ZATCA within 24 hours. The sale completes even if ZATCA is momentarily unreachable; the compliance obligation is the timely report, not a pre-clearance.
The dispatch decision — which flow a given invoice takes — is driven by the customer type and invoice class. Get it wrong and a B2B invoice takes the B2C path, reaching the business buyer without ever being cleared. It looks issued; it is not valid.
Where the tax rule meets the accounting record
Clearance and reporting are tax-authority events layered on top of the accounting entry — the Sales Invoice recognises revenue under the normal standard (Ind AS 115 / IFRS 15 equivalent) regardless of the ZATCA flow. What Phase 2 governs is whether the document is a valid tax invoice and when ZATCA has a record of it. Keep the two mental models separate: the ledger books the sale; the ZATCA layer decides the document's fiscal validity and the hash chain's integrity. Confirm the VAT and revenue treatment with your Saudi tax advisor.
Configure, dispatch, chain
Copy-paste the CSID and UBL 2.1 configuration steps, the two-path dispatch hook, the sequential hash-chain rules, and the operational habits that keep clearance from blocking billing.
There is a community erpnext_ksa / ZATCA app — verify its maintenance status for your version — or build the integration. Either way, these are the moving parts.
1. Onboard the CSID (Cryptographic Stamp Identifier):
• Generate a CSR, submit to ZATCA, receive the
compliance CSID, then the production CSID.
2. Set the invoice pipeline to emit UBL 2.1 XML with all
mandatory fields (seller/buyer, VAT, line items, UUID).
3. Wire the sign + transmit step to the correct flow:
• B2B -> clearance API (real-time, pre-delivery)
• B2C -> local stamp + report within 24h
4. Store on the Sales Invoice: ZATCA UUID, the returned
hash, the cleared/stamped QR (render on the PDF), and
the previous-invoice hash for the chain.
5. Test on the ZATCA sandbox before production onboarding.Onboard the CSID and emit UBL 2.1
Generate a CSR, obtain the compliance then production CSID from ZATCA, and build the pipeline to emit UBL 2.1 XML with every mandatory field and a UUID. Test on the ZATCA sandbox before production onboarding — the sandbox enforces the same schema the live platform will.
Dispatch each invoice to the right flow
One submit hook, two paths: a registered business customer routes to the clearance API and must be cleared before delivery; a consumer routes to local stamping plus a 24-hour report. Make the dispatch decision explicit and testable — this single branch is where B2B invoices leak into the wrong flow.
Store the stamp and render the QR
On each invoice, store the ZATCA UUID, the returned hash, the cleared or stamped QR, and the previous invoice's hash. Render the QR (base64) as an image on the Print Format. Both flows produce a QR; both must show it on the document.
Keep the hash chain intact
Each invoice references the previous invoice's hash, so the chain must be sequential and ordered with no gaps. Never delete or renumber a submitted e-invoice — the chain cannot be rebuilt around a hole — and handle cancellations through ZATCA's credit-note flow, not a raw delete. Reconcile the counter daily against ZATCA, the same discipline as the Indian e-invoice reconciliation.
When the till runs B2C and sales runs B2B
In a business with both a retail counter and a B2B sales desk, the two Phase 2 flows are owned by different people. The counter staff issue simplified invoices all day and never think about clearance; the sales desk issues standard invoices that must clear before they go out. The risk sits where the two meet — a B2B customer served at the counter, or a standard invoice raised on a screen configured for the simplified flow, goes out without clearance.
The control is to make the dispatch automatic and the customer's tax registration the trigger, not a human choice at issue time. Validate buyer VAT numbers at master-data setup so the B2B/B2C branch is reliable, and monitor both halves: CSID validity and clearance-API health for B2B, and the 24-hour reporting window for B2C. A dashboard that shows both keeps a certificate expiry or a reporting backlog from becoming a silent compliance failure.
Draft policy for your finance and IT leads to ratify. Every invoice's Phase 2 flow is determined automatically from the customer's tax registration — B2B standard invoices are cleared before delivery, B2C simplified invoices are stamped locally and reported within 24 hours. No B2B invoice is delivered to a business customer without a ZATCA clearance stamp. CSID validity and clearance-API health are monitored daily; B2C reporting is reconciled against the 24-hour window. Submitted e-invoices are never deleted or renumbered; cancellations use ZATCA's credit-note flow to preserve the hash chain. Confirm current field-level and wave requirements on the ZATCA portal and with your Saudi tax advisor before adoption.
Buy the app, or build the integration
FAQ
+What is the difference between clearance and reporting in ZATCA Phase 2?
Clearance is for B2B standard invoices: the invoice is signed with your CSID, sent to ZATCA's Fatoora platform, cryptographically stamped, and only then delivered to the buyer — in real time. Reporting is for B2C simplified invoices: they are stamped locally at issue and reported to ZATCA within 24 hours afterwards. B2B cannot be delivered until cleared; B2C completes immediately and is reported after.
+Which ZATCA wave am I in for Phase 2?
As of 31 July 2026 the latest is Wave 24 (announced 26 September 2025), covering businesses with VAT-taxable revenue above SAR 375,000 in 2022, 2023 or 2024, with compliance between 1 April and 30 June 2026. Waves capture progressively smaller taxpayers, and ZATCA notifies each wave about six months ahead — check the official announcement for the wave naming your business.
+Does ERPNext support ZATCA Phase 2 out of the box?
Not natively. There is a community erpnext_ksa / ZATCA integration whose maintenance status you should verify for your version; otherwise Phase 2 is a build — CSID onboarding, UBL 2.1 XML, the clearance/reporting dispatch, QR rendering, and the sequential hash chain. Sandbox-test the whole pipeline before production onboarding.
+What happens if a B2B invoice isn't cleared by ZATCA?
It is not a valid tax invoice and must not be delivered to the buyer. B2B clearance is real-time and pre-delivery, so if the Fatoora API is unreachable or your CSID is invalid, the invoice cannot be issued until clearance succeeds. Build retry and alerting so a transient ZATCA outage does not silently strand your billing.
+What is the ZATCA hash chain and why does it matter?
Phase 2 requires a sequential hash chain: each invoice carries the previous invoice's hash, so the sequence must be ordered with no gaps. It lets ZATCA detect missing or altered invoices. A broken chain — from a deleted, renumbered or reordered invoice — is a compliance failure even if every individual invoice is otherwise valid, which is why submitted e-invoices are never deleted.
+What invoice format does ZATCA Phase 2 require?
UBL 2.1 XML, with the mandatory fields, a UUID, a cryptographic stamp, and a QR code. B2B standard invoices are ZATCA-stamped through clearance; B2C simplified invoices carry a locally generated stamp and QR. Both must render the QR on the printed document.
Related issues you may also hit
- India's GST e-invoicing IRP round-trip — the clearance model in a different jurisdiction.
- The GST e-invoicing setup guide — a useful comparison template for configuring clearance-model e-invoicing.
- ERPNext multi-currency and multi-company setup — running a Saudi entity inside a wider group.
Closing
Phase 2 is not one integration with a toggle — it is two invoicing processes that must coexist and never cross wires. Confirm your wave, onboard the CSID, dispatch each invoice by customer type, and protect the hash chain like the audit trail it is. Get the split right at design time and clearance becomes a background step; get it wrong and a business customer receives an invoice that was never valid.
Facing a ZATCA Phase 2 wave deadline and unsure ERPNext is ready?
We map your B2B clearance and B2C reporting flows, stand up the CSID and hash chain in ERPNext, and sandbox-test the whole pipeline before your wave deadline lands.