ZATCA Phase 2 integration (Saudi Arabia)
Integrate with ZATCA through the Complyance API: set up a Saudi Arabian company, prepare its GETS invoice data and check the result of submission to ZATCA. Start with a workspace that includes Saudi Arabia.
Saudi Arabia e-invoicing uses ZATCA. In Complyance, first onboard the company, then send its invoice data in GETS through Unify. Test in the ZATCA sandbox before sending production documents, then follow the go-live checklist.
ZATCA Phase 2
ZATCA, Saudi Arabia’s Zakat, Tax and Customs Authority, introduced e-invoicing in two phases. Phase 1, the generation phase, has applied since 4 December 2021: invoices are issued from a compliant electronic solution. Phase 2, the integration phase, started on 1 January 2023 and reaches taxpayers in waves: the solution connects to ZATCA’s systems and sends each invoice in ZATCA’s format. See What is e-invoicing on ZATCA’s site, and check there when your wave starts.
Complyance is the connection to ZATCA for Phase 2. Each company you onboard gets its own e-invoicing identity with ZATCA, and every invoice you send through Unify is submitted under it.
Clearance and reporting
ZATCA treats the two kinds of tax invoice differently:
| Document | Usually issued to | What ZATCA does | documentType.base | government.status when accepted |
|---|---|---|---|---|
| Standard tax invoice, credit and debit note | A business (B2B) or government | Clearance: ZATCA checks each invoice and returns it stamped as cleared. | tax_invoice, credit_note, debit_note | CLEARED |
| Simplified tax invoice, credit and debit note | A consumer (B2C) | Reporting: you give the invoice to the customer, and it is reported to ZATCA afterwards. ZATCA rule BR-KSA-98 asks for the report within 24 hours of issue. | simplified_invoice, simplified_credit_note, simplified_debit_note | REPORTED |
You send both kinds the same way. Complyance clears or reports each one according to its documentType, and the result appears in the document’s status. Saudi Arabia examples has a request for each, with ZATCA’s answer.
What you send and what is added for you
A Phase 2 invoice carries fields that prove it was issued by a registered solution and has not been changed. You send the invoice content. Complyance adds the security fields when it builds the XML for ZATCA.
| Field | What it is | Who provides it |
|---|---|---|
| UUID (KSA-1) | A unique identifier for each invoice. | You, in header.uuid. Use a new UUID for every invoice. |
| Invoice counter value, ICV (KSA-16) | The invoice’s position in the sequence of invoices your system issues. Digits only. | You, in extensions.sa_icv. |
| Previous invoice hash, PIH (KSA-13) | The hash of the company’s previous invoice, which chains each invoice to the one before it. | Complyance. Leave extensions.sa_pih out. |
| Invoice hash and cryptographic stamp (KSA-15) | The invoice’s hash, signed with the company’s cryptographic stamp from onboarding. | Complyance. Leave extensions.sa_digitalSignature out. |
| QR code (KSA-14) | A code printed on the invoice, built from its data, hash and stamp. | Complyance, or ZATCA on a cleared invoice. Leave extensions.sa_qrCode out. |
The stamp comes from the CSID (cryptographic stamp identifier) that ZATCA issues when you onboard the company. Complyance keeps it for you; you never handle the certificate or its key.
Arabic on the invoice
ZATCA requires every field shown on the human-readable invoice, the copy a person reads, to be in Arabic. The invoice can be bilingual, with English as well. See ZATCA’s FAQ Should invoice be in English or Arabic?.
GETS has no separate Arabic fields for Saudi Arabia, such as an Arabic seller or buyer name. Send names and descriptions as they appear on your invoice.
What to check before sending
Use the Saudi Arabia field reference for the document type you are sending. The required data can differ between a tax invoice and a credit or debit note. Submit the values from the source document; do not fill missing amounts or identifiers with guesses.
After a successful request, follow the document until isTerminal is true. final_valid means ZATCA cleared the invoice or accepted its report. final_invalid means ZATCA rejected it; Saudi Arabia validation rules explains how to read the reason.