ZATCA Phase 2 Integration for Shopify: A Practical Guide for Saudi eCommerce Businesses

Saudi Arabia's ZATCA Phase 2 e-invoicing mandate is no longer a concern for large enterprises. Wave 25 has announced that July 24, 2026, marks the start of the Integration Phase for every VAT-registered business with revenues above SAR 187,500, with a February 1, 2027 deadline. Compliance is not built in for Saudi eCommerce businesses on Shopify. Shopify does not natively connect to ZATCA's Fatoora platform. The integration must be built outside the platform through a certified solution.

This guide covers what ZATCA Phase 2 integration for Shopify involves, the edge cases, and what to confirm before starting.

What ZATCA Phase 2 Means for Shopify Merchants

ZATCA Phase 2, known as the Integration Phase of Saudi Arabia's Fatoora e-invoicing programme, requires VAT-registered businesses to connect their invoicing systems directly to ZATCA's Fatoora platform. This is beyond a platform feature and is a government compliance mandate. For most eCommerce platforms in Saudi Arabia, this integration is handled natively. Salla and Zid both connect directly to Fatoora. Merchants on those platforms configure their settings and the compliance layer runs automatically.

Shopify is different, as it is a global commerce platform built for international selling. Its invoicing architecture handles VAT calculation, order management, and multi-currency selling across global markets. However, ZATCA Phase 2 requires real-time API integration with a Saudi government platform, cryptographic invoice signing with an ECDSA certificate, and UBL 2.1 XML invoice generation, which are not provided natively.

According to compliance requirements, Shopify merchants in Saudi Arabia must connect Shopify to a ZATCA-certified e-invoicing solution that handles Fatoora integration.

ZATCA Phase 2 Requirements for Shopify Stores

ZATCA's Integration Phase operates in two modes and every Shopify merchant in Saudi Arabia uses both.

Clearance Mode applies to B2B standard tax invoices. When a business buyer places an order using their VAT registration number, ZATCA must cryptographically clear the invoice before it is legally issued to the buyer. The buyer cannot receive the invoice until Fatoora stamps it.

Reporting Mode applies to B2C simplified tax invoices. The invoice is issued to the consumer at the point of sale and reported to Fatoora within 24 hours.

Every ZATCA-compliant invoice must meet five technical requirements: UBL 2.1 XML format, ECDSA cryptographic stamp using a ZATCA-issued CSID certificate, a UUID generated at invoice creation, a nine-tag TLV QR code including the invoice hash and digital signature, and a live API connection to Fatoora for clearance or reporting.

The checkout must detect buyer type automatically. A TRN field at checkout is the standard trigger. B2B orders route to clearance mode. B2C orders route to reporting mode. Routing a B2B order through the B2C path is a compliance defect.

Does ZATCA Phase 2 Apply to Your Shopify Business?

ZATCA rolls out Phase 2 in waves based on annual VAT-taxable revenue:

Wave 25 covers businesses whose VAT-subject revenues exceeded SAR 187,500 in any of 2022, 2023, 2024, or 2025. February 1, 2027 is the Wave 25 deadline specifically, not a universal deadline. Businesses in earlier waves that are not yet integrated are already non-compliant, whereas non-compliance carries penalties up to SAR 50,000 per violation.

How ZATCA Phase 2 Integration Works on Shopify

Shopify does not natively support ZATCA, but it is a proven architecture that connects Shopify to a certified invoicing engine via payment webhooks.

When a customer pays, Shopify fires an orders/paid webhook→The webhook handler posts the order payload to a ZATCA-certified invoicing engine→The engine builds the UBL 2.1 XML invoice, applies the cryptographic stamp using the store's CSID, generates the TLV QR code, and submits to Fatoora→The ZATCA acceptance status returns→The buyer receives a compliant PDF by email.

Shopify merchants can follow the three integration approaches below:

• App-based integration: ZATCA Tools (free), Simple Fatoora ($15.99 to $26.99 per month), and Marmin (free to install) are available in the Shopify App Store. All three are new, with 0 to 2 reviews as of September 2026. Merchants should verify current ZATCA certification status before installing any compliance-critical application.

• REST API with a certified invoicing engine: The proven approach for growing merchants. Certified providers connect to Shopify via a webhook and handle signing, QR code generation, queue management, and Fatoora submission, using asynchronous processing and offline buffering.
• Custom middleware: For enterprise Shopify Plus merchants with complex B2B operations or ERP connections, custom middleware provides the most control and reliability.

The Shopify ZATCA Edge Cases Most Guides Don’t Cover

The standard integration handles paid B2C orders cleanly. However, ZATCA compliance is won or lost on the scenarios that fall outside that path.

Refunds and Credit notes

A reported invoice cannot be edited or deleted, as every refund requires a credit note. It requires a new signed document referencing the original invoice's UUID, carrying the returned amounts and VAT, which is itself reported to Fatoora. This must be automated from the Shopify refund webhook, including partial refunds.

Cash on Delivery

Invoicing at dispatch for COD orders creates phantom tax liabilities when packages are refused. The clean approach is triggering invoices on delivery confirmation or payment capture. Where dispatch invoicing is operationally necessary, automate credit note generation on the return webhook.

BNPL Through Tabby and Tamara

The customer invoice is for the full order value with full VAT. The provider fee is a separate cost transaction, and excluding it from the customer invoice understates output VAT. This is the most common BNPL compliance error in Saudi eCommerce.

Promo Codes and Discounts

Discounts must be represented inside the invoice XML at line level or as document-level allowances so declared totals reconcile exactly. Applying the discount in the cart but not in the XML is a common cause of Fatoora rejection.

The 24-hour Reporting Window Under Peak Load

During White Friday or BFCM, high order volumes can push the oldest invoices past the 24-hour deadline before the queue drains. The invoicing engine must process asynchronously off the checkout path with offline buffering for Fatoora outages and automatic retry logic.

The Pre-Integration Checklist for Shopify ZATCA Phase 2

Before any development begins, confirm these ten items:

• Wave assignment and integration deadline
• VAT registration number active in Shopify tax settings
• Invoice type mix: proportion of B2B versus B2C orders
• TRN field at checkout configured for buyer type detection
• Current invoice generation method and ZATCA certification status
• ERP connectivity: whether compliance is handled at ERP or Shopify layer
• Refund webhook and automated credit note workflow
• COD invoicing trigger point and refused package credit note process
• Fatoora onboarding timeline: CSID certificate issuance takes two to four weeks
• Integration approach confirmed before any development begins

As a Shopify Plus Partner operating in Saudi Arabia, Codilar delivers end-to-end ZATCA Phase 2 integration covering invoicing architecture assessment, middleware development, CSID certificate management, Fatoora onboarding, and production validation. Codilar's Shopify Plus development services include the full integration lifecycle from pre-integration assessment through go-live.