ZATCA Phase 2 integration for online stores
ZATCA Phase 2 requires Saudi businesses selected for integration to connect their invoicing systems to the Fatoora platform. Invoices must follow the UBL 2.1 XML format, carry a digital signature and a QR code, and be sent to ZATCA through its API. Simplified tax invoices are reported within 24 hours. Standard tax invoices must receive ZATCA clearance before the buyer receives them.
For a WooCommerce store, this means connecting the order and refund process to an invoicing system that meets these requirements.
The integration deadline depends on the wave assigned to your business. Wave 25 has a deadline of 1 February 2027 for businesses that meet its revenue threshold.
What ZATCA Phase 2 integration means
ZATCA, the Zakat, Tax and Customs Authority, operates Saudi Arabia's electronic invoicing system, called Fatoora. Phase 2 is the integration stage of e-invoicing. It connects a business's invoicing software to ZATCA so invoices can be reported or cleared through the authority's API.
The integration covers more than the appearance of an invoice.
Your system must generate the required XML document, sign it using a certificate obtained through ZATCA's onboarding process, and include the required invoice information. It must also follow the invoice counter and previous invoice hash requirements.
The next step depends on the invoice type. A simplified tax invoice is reported after issue, within the 24-hour window. A standard tax invoice goes to ZATCA for clearance before it is given to the buyer.
For an online store, these requirements affect how invoices are created after an order is paid and how credit notes are handled when a refund occurs.
Phase 1 and Phase 2 have different requirements
Phase 1 is the generation stage. Phase 2 adds integration with ZATCA's Fatoora platform.
| Requirement | Phase 1 | Phase 2 |
|---|---|---|
| Invoice creation and format | Use a compliant e-invoicing system with the required invoice elements. Handwritten invoices and invoices made with text editors are prohibited. | UBL 2.1 XML format. |
| Invoice integrity | Uncontrolled access, tampering with invoices or logs, and multiple invoice sequences are prohibited. | Cryptographic signature using a certificate obtained through ZATCA onboarding. |
| QR codes | Required on simplified invoices (B2C). Optional on tax invoices (B2B). | QR code includes cryptographic fields. |
| Connection to ZATCA | No connection. Invoices are neither reported nor cleared. | Documents are sent to ZATCA through its API. |
| Simplified invoice reporting | No reporting to ZATCA. | Report simplified invoices within 24 hours. |
| Standard tax invoice clearance | No clearance by ZATCA. Tax invoices must include the buyer's VAT number when the buyer is VAT-registered. | Standard tax invoices must be cleared by ZATCA before they are given to the buyer. |
Source: ZATCA, How to prepare for Phase 1, which explains the requirements of the generation phase that began on 4 December 2021.
The main difference for a business moving to Phase 2 is the connection to ZATCA.
Generating an invoice inside WooCommerce is only part of the process. The invoicing system must also handle certificates, signing and communication with Fatoora.
Phase 2 introduces different submission rules for simplified and standard tax invoices. Your store needs the correct process for each type it issues.
Simplified and standard tax invoices follow different processes
The distinction between simplified and standard invoices matters because ZATCA handles them differently.
Simplified tax invoices are reported within 24 hours
Simplified tax invoices are used for B2C transactions.
The invoicing system creates the document, signs it and includes the required QR code. It then reports the invoice to ZATCA within 24 hours.
Reporting can happen in the background after an invoice has been issued.
A temporary network problem does not remove the reporting requirement. The system needs a way to retry submissions while remaining within the required window.
Standard tax invoices need clearance before issue
Standard tax invoices are used for B2B transactions.
They must be sent to ZATCA for clearance before they are given to the buyer. This makes the timing different from simplified invoice reporting.
A WooCommerce store that sells to businesses needs a way to collect the buyer information required for standard invoices. The invoicing system must submit the standard invoice for clearance and handle the response before the buyer receives the document. If your store has both B2C and B2B orders, check that your integration supports both invoice processes.
What a Phase 2 integration must handle
Phase 2 brings several technical requirements into the invoicing process. Each serves a specific purpose.
XML documents using UBL 2.1
Invoices are created as XML documents using UBL 2.1. The XML document contains the invoice information in the format used for ZATCA integration.
A customer-facing invoice page may present the information differently. The XML document is the record created for the integration process.
For a WooCommerce store, the invoicing system needs to produce the required XML from the order information.
Digital signing with a ZATCA certificate
Invoices must be cryptographically signed.
The signing process uses a certificate obtained through ZATCA onboarding. That certificate is associated with the invoicing system used by the taxpayer.
Onboarding establishes the certificate credentials before production invoicing begins.
The certificate has an expiry date. A store must monitor its validity and complete onboarding again when renewal is needed.
QR codes with invoice information
The QR code carries specific invoice information.
For the WooCommerce implementation described in this guide, the QR data includes:
- Seller name and VAT number
- Invoice date and time
- Invoice total and VAT amount
- Invoice hash
- Digital signature
These values are encoded using ZATCA's TLV tags. The QR code forms part of the invoice document presented to the customer.
Invoice counters and previous invoice hashes
Each invoice document carries an invoice counter, called ICV, and a previous invoice hash, called PIH. The previous hash connects a document to the preceding document in the sequence.
This creates a requirement for the invoicing system when several orders are paid close together. The documents must be generated in the correct sequence so their counters and hashes remain consistent.
Raseedo handles this by creating signed documents one at a time, including when checkouts occur simultaneously.
Communication with the Fatoora API
After the document has been created and signed, the integration communicates with ZATCA through its API.
For simplified invoices, it reports the document within 24 hours. For standard invoices, it requests clearance before the buyer receives the invoice.
The integration must also handle ZATCA's responses.
A rejected document needs attention. An interruption in the connection may require another submission attempt. These are operational matters for the store, not only tasks performed during initial setup.
How ZATCA onboarding works
A Phase 2 integration needs a certificate before it can issue production invoices. ZATCA provides an onboarding process through the Fatoora portal.
Generate the one-time password
The taxpayer signs in to the Fatoora portal at fatoora.zatca.gov.sa and generates a one-time password, called an OTP. The OTP contains six digits and remains valid for one hour. The invoicing system uses this password to begin the certificate process.
Because the password has a limited validity period, generate it when you are ready to complete onboarding.
Obtain the compliance certificate
The invoicing system creates its cryptographic key and certificate signing request. It then uses the OTP to request a compliance certificate, called a CSID.
This certificate is part of the onboarding process. It is not the final production certificate.
Complete the compliance checks
The system must pass ZATCA's compliance checks. These involve six sample documents submitted through the onboarding process. Once the required checks have passed, the system can request its production certificate.
Obtain the production certificate
After successful compliance checks, the system obtains the production certificate used for issuing invoices through the production integration. The certificate and its associated key must be stored so the invoicing system can continue signing documents. If the certificate expires, the store needs to complete onboarding again with a new OTP.
Choose the correct environment
ZATCA provides three environments for integration work.
| Environment | Purpose |
|---|---|
| Developer portal sandbox | Testing with test data, without requiring an account |
| Simulation | Testing with a real VAT number, without legally issuing invoices |
| Production | Issuing invoices through the production integration |
The sandbox allows development and initial testing.
Simulation provides a separate environment using an actual VAT number. Documents issued there are not legally issued invoices.
Production is the environment used for live invoicing. Make sure you understand which environment your store is connected to before turning on production invoicing.
Credit notes and debit notes need attention
A refund can require an invoicing document associated with the original invoice. For WooCommerce refunds, Raseedo generates a credit note that references the original invoice and includes the refund reason. The invoice type matters here as well.
A refund for a simplified invoice produces a simplified credit note. With Raseedo Pro, a refund for a B2B standard invoice produces a standard credit note.
This keeps the refund document associated with the invoice that was originally issued.
Raseedo's XML builder supports debit notes, and onboarding passes ZATCA's debit-note compliance samples. However, neither WooCommerce nor Raseedo has a debit-note action, so the plugin currently issues only invoices for paid orders and credit notes for refunds, as explained on the credit notes page.
Who must integrate and when
ZATCA introduces Phase 2 integration in waves.
Each wave has its own selection criteria and integration deadline. ZATCA notifies targeted taxpayers at least six months before their assigned date.
Wave 25 covers businesses whose VAT-subject revenue exceeded SAR 187,500 in any one of these years:
- 2022
- 2023
- 2024
- 2025
The integration deadline for Wave 25 is 1 February 2027.
The threshold applies to revenue in any one of the listed years. It does not require the business to exceed SAR 187,500 in every year.
Wave 24 used a higher threshold of SAR 375,000. If your business falls within the Wave 25 criteria, review the notice from ZATCA and prepare your invoicing integration before the deadline. Read the Wave 25 deadline and eligibility guide for the threshold, dates and preparation steps.
ZATCA does not require software to be approved
ZATCA does not certify e-invoicing software for taxpayers.
Its Solution Providers Directory is indicative. A software provider does not have to appear in that directory for its customers to meet the requirements.
What matters is whether the invoicing system meets ZATCA's requirements. This is an important distinction when comparing software for your store.
A statement that a plugin is listed by ZATCA is different from a claim that ZATCA has certified or approved it. The directory does not provide that certification.
When reviewing a plugin, focus on the functions it implements, including XML generation, certificate onboarding and the appropriate reporting or clearance process. You should also understand how the plugin handles rejected documents and interruptions in communication with ZATCA.
What Phase 2 means for a WooCommerce store
A WooCommerce integration needs to connect invoice creation to the store's order process. For a paid B2C order, the system needs to create a signed simplified invoice, include its QR code and report it to ZATCA within 24 hours.
For a B2B order, the store needs to collect the buyer details required for a standard invoice. That invoice must receive clearance before it reaches the buyer.
Refunds must be considered alongside the original orders.
Store owners also need access to their invoicing records. Signed XML files and responses from ZATCA are useful when reviewing the status of a document.
An invoicing system should make rejected submissions visible so they can be investigated.
Before starting, check your WooCommerce installation, seller details and intended ZATCA environment. Determine whether your orders require simplified invoices, standard invoices or both.
These decisions affect the plugin functions your store needs.
How Raseedo handles WooCommerce integration
Raseedo is a WordPress plugin for Saudi WooCommerce stores.
The free plugin handles certificate onboarding and simplified tax invoices. You enter the Fatoora OTP, and Raseedo creates the key and certificate request, completes the six compliance checks and obtains the production certificate.
For paid orders, it generates signed UBL 2.1 XML invoices with QR codes. Reporting runs in the background through WooCommerce's Action Scheduler.
The plugin retries temporary communication failures and displays ZATCA rejection reasons in the E-invoices tab. Signed XML documents and ZATCA responses remain on your WordPress site.
Customers receive access to a bilingual Arabic and English invoice page through their order details and emails. Raseedo Pro adds B2B standard invoices with ZATCA clearance, buyer VAT details at checkout, and reports for missing invoices. Raseedo is independently developed and is not affiliated with, endorsed or approved by ZATCA.
For the required seller information and certificate process, follow the Raseedo setup guide.