ZATCA Phase 2 for E-Commerce: How Saudi Online Retailers Can Achieve Compliance

The short answer: an online store falls under ZATCA Phase 2 like any other seller, but its invoices are raised by software events rather than by a cashier. Most consumer orders produce simplified tax invoices that your own system stamps, adds a QR code to and reports to ZATCA within 24 hours. Orders from VAT-registered businesses produce standard tax invoices that must be cleared before the buyer receives them. Every refund, return or price change produces a credit or debit note that references the original invoice. The real work is wiring those documents to the right store events and keeping the submission queue reliable. For the general Phase 2 rules (onboarding, CSIDs, the hash chain, deadlines and penalties), read our ZATCA Phase 2 e-invoicing guide; this post covers what is specific to e-commerce.

Online shopping is mainstream in the Kingdom. The General Authority for Statistics' ICT Access and Usage survey 2025 found that 71.0% of individuals aged 15-74 bought goods or services online, rising to 80.2% among Saudis. At that volume, an e-invoicing bug is not an edge case; it repeats on every order.

Which document does each online order need?

ZATCA's rules follow the buyer, not the sales channel. ZATCA's own Detailed Guidelines for E-Invoicing use an online pharmacy as a worked example: once the customer has paid, the store issues a simplified tax invoice through its app and emails it to the customer's registered address. The guideline allows electronic sharing when the parties agree.

The codes and field rules come from ZATCA's XML Implementation Standard. A B2B checkout needs more fields: a standard invoice must carry the buyer's name and a street, city and country code (business rules BR-KSA-42 and BR-KSA-10), and a buyer VAT number, where given, must be 15 digits that start and end with 3 (BR-KSA-44). Validate them at checkout.

Mapping store events to ZATCA documents

The safest rule is to issue the invoice at the event that completes the sale in your business model, then issue notes, never edits, for everything that happens afterwards.

• Payment captured. For prepaid card, mada, wallet or BNPL orders, the payment-confirmed event is the natural trigger. On Shopify that is the orders/paid webhook, which Shopify's webhook topic reference says occurs whenever an order is paid; on WooCommerce it is the woocommerce_payment_complete action in WooCommerce's order class.
• Cash on delivery. No payment event exists at checkout, so agree with your tax adviser whether the invoice is raised at dispatch or at delivery, and apply that rule consistently across every order.
• Refund created. Shopify's refunds/create topic fires when a refund is created on an order, independent from the movement of money. WooCommerce fires woocommerce_order_refunded with the order and refund IDs, plus partial and full variants, from its order functions.
• Cancellation. If an order is cancelled before an invoice was issued, there is nothing to reverse. After issue, ZATCA's guidelines are explicit that invoices cannot be cancelled, so a cancellation becomes a credit note.

Refunds, returns and credit notes

The rules to build in:

• Always reference the original invoice. ZATCA's guidelines state that issuing a credit note without reference to the original invoice violates Article 54 of the VAT Implementing Regulations. One note can cover several invoices, and the reference field accepts a range of invoice numbers.
• State the reason. The XML standard requires every credit and debit note to carry the reason it was issued (rule BR-KSA-17).
• Match the type of the original. A note against a simplified invoice is itself simplified and is reported within 24 hours; a note against a standard invoice goes through clearance.
• Credit only what was refunded. A partial refund produces a credit note for the refunded lines, their VAT and any refunded shipping, not a reversal of the whole order.
• Handle exchanges as two documents: a credit note for the returned item and a new invoice for the replacement.

Marketplaces and third-party invoicing

If you also sell through a marketplace, establish who issues the tax invoice. ZATCA's guidelines say the e-invoicing rules cover not only the resident seller but also a customer or third party that issues a tax invoice on the seller's behalf. The XML carries a flag for this: position 3 of the invoice transaction code (KSA-2) marks a third-party invoice, alongside flags for nominal, export, summary and self-billed invoices. Self-billing, where the buyer issues the invoice, applies only to B2B and requires a self-billing agreement approved by ZATCA, according to ZATCA's E-Invoicing Detailed Technical Guideline.

If the marketplace invoices on your behalf, your system must not issue a second invoice for the same sale. If you invoice marketplace orders yourself, route them through the same e-invoicing layer as your own store.

Integration patterns by platform

Shopify

A custom app subscribes to orders/paid, refunds/create and orders/cancelled, builds the UBL XML, stamps simplified invoices and queues them for reporting. Shopify warns that an app may receive the same webhook more than once, recommends idempotent processing, and advises a reconciliation job that periodically fetches data the app might have missed. For ZATCA, that means keying every document to the Shopify order or refund ID, so a repeated webhook can never produce a second invoice number.

WooCommerce

A plugin hooks the payment-complete and refund actions and shows the invoice UUID and reporting status on each order. Because WooCommerce runs on your own hosting, keep the private key behind your CSID outside the web root.

Custom and headless platforms

Mantiqi builds a standalone e-invoicing microservice that accepts order and refund events through an API or message queue, keeps the counter and hash chain, and manages the reporting queue, so a slow ZATCA response never blocks a payment.

Building a reporting queue that survives peak season

Ramadan, White Friday and Saudi National Day multiply the documents you must submit, and ZATCA's technical guideline shapes the design:

• One document per call. ZATCA says there is currently no option to report simplified invoices in bulk, so size your workers for your busiest day, not an average one.
• Retries are safe if they resend the same document. Fatoora does not reject a document for being submitted twice and counts each invoice once, based on its UUID and hash. A retry must resend the stored XML, never regenerate it.
• Never block on the previous invoice. Clearance does not change the invoice hash, so you can keep generating documents without waiting for the previous clearance response.
• Plan for clearance being switched off. If ZATCA disables clearance, it returns a 303 response and standard invoices are submitted through the reporting API instead.
• Watch the 24-hour clock. Alert on any simplified document still unreported after a few hours, well before the deadline.

Common pitfalls

• Editing or deleting issued invoices to reflect a return, instead of issuing a credit note.
• Wrong tax category per line. In ZATCA's online pharmacy example, two items carry VAT at 15% and a third, a medical good, is zero-rated on the same invoice, as set out in the Detailed Guidelines. Every line needs the right category code (S, Z, E or O).
• English-only invoice PDFs. ZATCA's guidelines require any information in the human-readable invoice to be in Arabic; translation may be added alongside.
• Gaps in the counter. ZATCA expects no gaps in the counter value or the previous-invoice-hash sequence, so allocate invoice numbers when a document is issued, not when a cart or order is created.

How Mantiqi can help

Mantiqi's team has developed ZATCA-compliant e-invoicing integrations for Saudi businesses and has built a high-volume e-commerce payment aggregator. Our ZATCA e-invoicing service covers onboarding, the reporting queue and credit-note flows, our payment solutions team connects them to your gateway, and our web development team handles the storefront. See how this fits the wider retail and e-commerce picture, read our guides to Saudi payment gateway integration and AI personalisation for Saudi retailers, or contact us for a ZATCA assessment of your online store.