Skip to main content

GST & compliance

ZATCA Phase 2 Wave 25 in ERPNext: Clearance vs Reporting

ZATCA Phase 2 runs two flows in one ERP: B2B standard invoices are cleared before the buyer gets them; B2C simplified ones are reported within 24 hours.

Updated 11 Nov 20268 min readBy ManojFirst published 31 Jul 2026

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.

In scope: integration was due by 30 June 2026

Taxable revenue above SAR 375,000 in 2022, 2023 or 2024 falls within Wave 24 or an earlier wave, which was due by 30 June 2026. If you are not yet integrated with Fatoora, treat it as overdue and check ZATCA's notification to your business.

Wave 25 threshold (SAR 187,500; integrate by 1 Feb 2027) as of 12 Oct 2026. Waves and thresholds move: ZATCA’s notification to your business 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 Standard Invoice — Clearance
Sign point
Signed with the taxpayer CSID before delivery
ZATCA step
Transmitted to the Fatoora clearance API and cryptographically stamped by ZATCA
Timing
Real-time, BEFORE the buyer receives the invoice — no stamp, no valid invoice
Format
UBL 2.1 XML with the ZATCA-cleared QR
Failure mode
Clearance API down or CSID invalid → invoice cannot be issued to the buyer

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, 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.

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.

text
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.

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 specNo maintained app matches your version
Standard B2B + B2C flows, no unusual requirementsBespoke document types or approval flows
You want fastest time to a compliant go-liveYou need full control of the sign/clearance pipeline
Small IT team, prefer a supported dependencyIn-house capability to track ZATCA spec changes
Either way: verify the app is current with ZATCA's evolving fields before relying on itEither way: sandbox-test the full clearance + hash chain before production

At a glance

AspectWhat to know
B2B standard invoiceCleared by ZATCA before it is shared with the buyer
B2C simplified invoiceStamped 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 ERPNextksa_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.

In the UAE? See the UAE e-invoicing timeline.

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.

Your next step

GST & compliance

Now see GST compliance

Comments & ratings

No comments yet. Start a new discussion.

0

Manoj · Published on 31 July 2026

Worked with us? Leave a Google review

Questions about this? Talk to the team.

Book a 30-minute Google Meet, WhatsApp us, or send a message. The engineer who works on this replies.

Send us a message

Your details go to our team's CRM and are used only to reply.