Invoice Docs
ZATCA

ZATCA support is used for businesses that require Saudi e-invoicing.

Where to configure

Open Subscription > Add-ons > ZATCA add-on.

ZATCA add-on settings (placeholder)

You can:

  • Enable ZATCA
  • Select QR/compliance mode
  • Start onboarding
  • View onboarding status/details
  • Save ZATCA settings

ZATCA onboarding status/details (placeholder)

ZATCA modes

ModeStatus behaviorDescription
Basic QR (Offline)OFFLINEGenerates basic QR data without digital signing/submission.
Signed (Not Submitted)SIGNED_NOT_SUBMITTEDDigitally signs invoice QR but does not submit/report.
Reported (Phase 2)REPORTED/CLEARED or pending/failureSigns and submits to provider/ZATCA flow.

Invoice types

The ZATCA processing supports:

  • SIMPLIFIED
  • STANDARD

If invoice type is not specified, it defaults to simplified behavior.

What happens when saving an invoice

When ZATCA is enabled and configured:

  1. The invoice is processed before saving.
  2. Seller name, VAT number, invoice timestamp, total amount, and VAT amount are collected.
  3. QR data is generated.
  4. If signing material exists, the invoice is signed.
  5. If reported mode is enabled, the invoice is submitted/reported/cleared through the provider flow.
  6. ZATCA metadata is stored inside invoice details.
  7. zatca_status is stored on the invoice record when available.

Possible ZATCA statuses

Common statuses include:

  • OFFLINE
  • SIGNING_REQUIRED
  • SIGNED_NOT_SUBMITTED
  • REPORT_PENDING
  • REPORTED
  • CLEARED
  • FAILED/REJECTED depending on provider response

Public link restriction

For standard invoices:

Invoice type STANDARD must have ZATCA status CLEARED before public sharing.

This prevents sharing a standard invoice before clearance.

ZATCA template

Template 4 is used for ZATCA-style invoices and QR display.

Required configuration

ZATCA production use may require:

  • ZATCA add-on active
  • Business VAT number
  • ZATCA onboarding completed
  • Private key/signing material
  • Certificate reference
  • Provider endpoint/API credentials
  • Correct invoice type

Best practices

  • Test in sandbox before production.
  • Confirm VAT number and seller name are correct.
  • Use ZATCA template for Saudi invoices.
  • Check ZATCA status from invoice list/preview before sharing.
  • Do not edit cleared invoices without a proper correction/credit-note workflow.
GST FilingTroubleshooting