ZATCA's Phase 2 ("Integration") doesn't add one e-invoicing flow to your ERP; it adds two, side by side. A B2B standard invoice is signed with your CSID and must be cleared by ZATCA's Fatoora platform before it is shared with the buyer. A B2C simplified invoice is stamped locally, given to the buyer at once, and reported to ZATCA within 24 hours. Same system, different sign points, different failures. This guide covers the split, the CSID and hash chain, and how it lands in ERPNext. It describes the integration, not tax advice: confirm your obligations on the ZATCA portal or with a Saudi tax adviser.
What is ZATCA Phase 2 Wave 25?
ZATCA e-invoicing Phase 2 (the integration phase) means your invoicing system must connect to ZATCA's Fatoora platform. Wave 25 is ZATCA's latest group of taxpayers that must integrate with the Fatoora platform (ZATCA, 24 July 2026). It covers businesses with taxable revenue above SAR 187,500 in 2022, 2023, 2024 or 2025, and the integration deadline is 1 February 2027. ZATCA notifies the targeted taxpayers; its notification to you is what counts. Phase 1 only required generating e-invoices. Phase 2 adds integration: B2B standard invoices are cleared by ZATCA before sharing, and B2C simplified invoices are reported within 24 hours. Read against ZATCA's news page on 11 November 2026; no later wave was announced. Use the wave checker below, then talk to us about your deadline.
The trap in Phase 2 is treating it as one integration: once a B2B invoice slips into the B2C path, it reaches the buyer without clearance. I am Manoj, and I lead ERPNext and Frappe work at MithTech, a team of Frappe specialists in Bengaluru. The clearance-versus-reporting split is the key design decision in a Saudi ERPNext rollout.
Are you in scope yet?
Phase 2 rolls out in waves, each reaching smaller taxpayers. Establish which wave names your business first; ZATCA notifies taxpayers in each wave.
Calculator
Wave / Scope Checker
Enter your highest annual VAT-taxable revenue to see roughly where you fall against the announced ZATCA Phase 2 waves. Wave 25 (above SAR 187,500 in 2022–2025, by 1 February 2027) is the latest as of 11 November 2026; ZATCA's notification to you is what counts.
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:
Interactive
Clearance vs Reporting Flow Decider
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.
B2B is clearance: the invoice is signed with your CSID, sent to the Fatoora clearance API, stamped by ZATCA, and only then shared with the buyer. If the clearance API is unreachable or your CSID is invalid, you can't share the invoice, so your billing depends on ZATCA's uptime.
B2C is reporting: the simplified invoice is stamped locally at the point of sale, handed to the customer at once, and reported to ZATCA within 24 hours of generation. The sale completes even if ZATCA is briefly unreachable; the obligation is the timely report.
Which flow an invoice takes is driven by the customer type and invoice class. Get it wrong and a B2B invoice takes the B2C path and reaches the business buyer without clearance. It looks issued; it isn't compliant.
Configure, dispatch, chain
Code recipe
Configure · Dispatch · Hash-chain · Prevent
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.
0 of 4 steps done
Tick a step’s number when it is done; the ticks stay on this device.
Onboard the CSID and emit UBL 2.1
Generate a CSR, obtain the compliance and then production CSID from ZATCA, and build the pipeline to produce UBL 2.1 XML with every mandatory field and a UUID. Test in ZATCA's sandbox before production onboarding.
Dispatch each invoice to the right flow
One submit hook, two paths: a VAT-registered business customer goes to the clearance API and must be cleared before sharing; a consumer goes to local stamping plus a report within 24 hours. Make the branch explicit and testable; it is where B2B invoices leak into the wrong flow.
Store the stamp and render the QR
On each invoice, store the UUID, the 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, and both show it on the document.
Keep the hash chain intact
Each invoice references the previous invoice's hash, so the chain must be sequential with no gaps. Never delete or renumber a submitted e-invoice, and handle corrections through credit and debit notes, not a delete. Reconcile the counter daily against ZATCA's records.
When the till runs B2C and sales runs B2B
In a business with both a retail counter and a B2B sales desk, different people own the two flows. Counter staff issue simplified invoices all day and never think about clearance; the sales desk issues standard invoices that must clear first. The risk sits where they meet: a B2B customer served at the counter, or a standard invoice raised on a screen set up for the simplified flow.
Make the routing automatic, triggered by the customer's VAT registration, not a choice at issue time. Check buyer VAT numbers when masters are set up so the branch is reliable, and monitor both halves: CSID validity and clearance-API health for B2B, and the 24-hour window for B2C. One dashboard for both stops a certificate expiry or a reporting backlog going unnoticed.
Draft policy for your finance and IT leads to ratify. Every invoice's Phase 2 flow is set automatically from the customer's tax registration: B2B standard invoices are cleared before they are shared, B2C simplified invoices are stamped locally and reported within 24 hours. No standard invoice is shared with a business customer without ZATCA clearance. 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; corrections use credit and debit notes to preserve the hash chain. Confirm current field-level and wave requirements on the ZATCA portal and with your Saudi tax adviser before adoption.
Use an app, or build the integration?
| Use a ZATCA app (ksa_compliance, zatca_erpgulf) | Build the integration |
|---|---|
| A maintained app covers your version and current spec | No maintained app matches your version |
| Standard B2B + B2C flows, no unusual requirements | Bespoke document types or approval flows |
| You want fastest time to a compliant go-live | You need full control of the sign/clearance pipeline |
| Small IT team, prefer a supported dependency | In-house capability to track ZATCA spec changes |
| Either way: verify the app is current with ZATCA's evolving fields before relying on it | Either way: sandbox-test the full clearance + hash chain before production |
At a glance
| Aspect | What to know |
|---|---|
| B2B standard invoice | Cleared by ZATCA before it is shared with the buyer |
| B2C simplified invoice | Stamped locally; reported within 24 hours |
| Latest wave (11 Nov 2026) | Wave 25: above SAR 187,500 in 2022–2025, integrate by 1 Feb 2027 |
| In ERPNext | ksa_compliance or zatca_erpgulf app, or a custom build |
FAQ: what do people ask most?
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, stamped, and only then shared with the buyer. Reporting is for B2C simplified invoices: they are stamped locally, given to the buyer at once, and reported to ZATCA within 24 hours. A standard invoice waits for clearance; a simplified one is reported after.
Which ZATCA wave am I in for Phase 2?
As of 11 November 2026 the latest announced is Wave 25 (ZATCA, 24 July 2026): VAT-taxable revenue above SAR 187,500 in 2022, 2023, 2024 or 2025, with integration by 1 February 2027. Wave 24 (above SAR 375,000 in 2022–2024) was due by 30 June 2026. ZATCA notifies each wave at least six months ahead; its notification to your business is what counts.
Is the Fatoora platform the same as ZATCA e-invoicing Phase 2?
No. Fatoora is ZATCA's e-invoicing platform. Phase 2, the integration phase, requires your e-invoicing solution to integrate with that platform, issue invoices in a set format and carry extra fields, as ZATCA states in its Wave 25 announcement. Logging in to the portal does not make your invoicing system compliant.
Does ERPNext support ZATCA Phase 2 out of the box?
Not natively. Community apps exist, notably lavaloon-eg/ksa_compliance and ERPGulf/zatca_erpgulf, both active in October 2026 when we checked; verify one for your version. Otherwise Phase 2 is a build: CSID onboarding, UBL 2.1 XML, the clearance/reporting routing, QR rendering and the hash chain. Test the pipeline in ZATCA's sandbox before production onboarding.
What happens if a B2B invoice isn't cleared by ZATCA?
Don't share it with the buyer: clearance is the prerequisite for sharing a standard invoice. If the Fatoora API is unreachable or your CSID is invalid, the invoice waits until clearance succeeds. Build retry and alerting so a short ZATCA outage doesn't quietly hold up 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 each 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.
What related issues might you also hit?
In the UAE? See the UAE e-invoicing timeline.
- EU VAT triangulation in ERPNext: another rule where one invoice element decides the outcome.
- ERPNext multi-currency and multi-company setup: running a Saudi entity inside a wider group.
What is the bottom line?
Phase 2 is not one integration with a toggle: it is two invoicing processes that must run side by side without crossing. Confirm your wave, onboard the CSID, route each invoice by customer type, and protect the hash chain as the audit trail it is.
Facing a ZATCA Phase 2 wave deadline on ERPNext?
MithTech is a team of Frappe specialists. We set up the B2B clearance and B2C reporting flows, the CSID and the hash chain in ERPNext, and test the pipeline in ZATCA's sandbox before your deadline. See our VAT setup.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 31 July 2026
Worked with us? Leave a Google review