Configure ZATCA e-invoicing for Saudi Arabia
The Zakat, Tax and Customs Authority (ZATCA) β Saudi Arabia e-invoicing integration submits Zenoti invoices to the Saudi Arabian tax authority's Fatoora platform. Once configured, every invoice closed at an enabled Saudi center is formatted, signed, and reported to ZATCA, and the cryptographic stamp and QR code are printed on the guest receipt.
Note: For a conceptual overview of regional compliance integrations, see the Integrations overview.
Region served: Saudi Arabia only. ZATCA is the Saudi federal tax authority.
ZATCA e-invoicing phases: ZATCA introduced e-invoicing in two phases.
- Phase 1 (Generation) required Saudi businesses to generate and issue electronic invoices and credit/debit notes with QR codes. Zenoti-generated invoices meet the Phase 1 content and QR code requirements automatically.
- Phase 2 (Integration) requires businesses to integrate their billing systems with ZATCA's Fatoora platform so that each invoice is cryptographically stamped, reported in near real time (for tax invoices / B2B) or cleared within a window (for simplified invoices / B2C), and includes a QR code with the ZATCA cryptographic signature.
This integration implements Phase 2. If your business was onboarded to ZATCA's Phase 2 wave applicable to your revenue bracket, this is the integration you configure.
Deployment model: Fatoora is a cloud service operated by ZATCA. Zenoti submits invoices via the Fatoora API over the public internet. There is no on-premise component on the Zenoti side. Real-time submission is required for Phase 2 β offline batching is not supported.
Audience: Organization administrators who are responsible for Saudi Arabia fiscal compliance configuration.
On this page
- Before you begin
- External-system prerequisites
- Network requirements
- Supported document types
- Seller registration types
- Configure ZATCA credentials
- Configure invoice settings
- Enable per center
- How it works
- Failure paths
- Edit or cancel a submitted invoice
- Refunds, credit notes, and debit notes
- Reconciliation
- Tips
- Troubleshooting
Before you begin
Permission: You need organization administrator access to configure regional compliance integrations.
- Your organization must have the ZATCA e-invoicing feature enabled. This is an organization-level flag scoped to Saudi Arabia β contact Zenoti Support to confirm it is active for your organization.
- Each Saudi center must have accurate bilingual (English + Arabic) address, VAT registration number, and legal name captured before enabling ZATCA.
- You need valid Fatoora API credentials issued by ZATCA before starting configuration.
- ZATCA configuration is stored and retrieved per center. You must complete configuration separately for each Saudi center in your organization.
External-system prerequisites
1. Register with ZATCA and enrol in Phase 2
- Your business must be registered with ZATCA and hold a valid VAT registration number (TIN).
- Complete Phase 2 onboarding in the ZATCA Fatoora portal. ZATCA onboards businesses in waves based on revenue β confirm your wave date and obtain your Fatoora API credentials.
- If the portal enrolment is unfamiliar, consult the ZATCA Fatoora portal's official documentation β ZATCA updates the onboarding process periodically.
2. Obtain Fatoora API credentials
- ZATCA issues an API key that Zenoti uses to authenticate against the Fatoora API via the
x-api-keyheader. This key is specific to your business and must be handled as a secret. - Record the API host URL Fatoora provides. Sandbox and production URLs differ β confirm which environment your credentials are for.
3. Identify your seller registration type
ZATCA requires every seller to declare a registration type on each submission. Confirm the correct value with your ZATCA account manager before you begin configuration. See Seller registration types for the supported values.
4. Capture bilingual business details
- ZATCA invoices carry seller and buyer fields in English AND Arabic. Before enabling, verify every field (legal name, address, city, district, building number, region) has both an English and an Arabic value captured in Zenoti. Missing Arabic values will cause validation failures.
5. Capture buyer details for B2B
For B2B invoices, ZATCA requires the buyer's VAT number and bilingual address. Train front-desk staff to collect these before closing a B2B invoice. For B2C invoices, buyer details are optional.
Network requirements
| Direction | Port | Protocol | Endpoint to allowlist |
|---|---|---|---|
| Outbound: Zenoti β ZATCA Fatoora API | 443 | HTTPS | The Fatoora API host URL provided by ZATCA (sandbox or production). |
No inbound connectivity is required. If Fatoora is unreachable, submissions fail at closure and must be retried manually.
Supported document types
The following document types are supported for ZATCA submission. Zenoti selects the document type automatically at submission based on buyer data and whether the invoice references a parent invoice.
| Document type | Description |
|---|---|
| B2B invoice | Tax invoice issued to a VAT-registered business. Requires buyer VAT number. |
| B2C invoice | Simplified tax invoice issued to an individual consumer. Buyer details optional. |
| B2B credit note | Credit note against a B2B invoice β reduces the taxable amount. |
| B2B debit note | Debit note against a B2B invoice β increases the taxable amount. |
| B2C credit note | Credit note against a B2C invoice. |
| B2C debit note | Debit note against a B2C invoice. |
Refund workflows produce credit notes. Upward corrections produce debit notes.
Seller registration types
ZATCA classifies sellers by registration type. The correct value depends on your business licence. Confirm your type with your ZATCA account before configuration.
| Registration type | Typical use |
|---|---|
| CRN (Commercial Registration Number) | Most commercial businesses. |
| ML (Municipal License) | Municipality-licensed businesses. |
| MLSDL (Ministry of Labor / SDL) | Labor / social development registrations. |
| SL (SAGIA License) | Foreign investment / SAGIA-registered entities. |
| OL (Other License) | Any other ZATCA-recognised licence. |
Configure ZATCA credentials
ZATCA configuration is stored and retrieved per center. Complete the following steps for each Saudi center.
Steps
Select the center in the scope selector, navigate to Configuration > Integrations > Integration Settings, and expand Zatca e - Invoicing.
Enter the following values. All values come from your ZATCA Fatoora enrolment β Zenoti does not supply defaults.
Field Source What to enter Org Legal Name Your own tax registration. Legal name as registered with ZATCA. Center Building Number Saudi National Address registration. Building number for the seller address. Center District Saudi National Address registration. District for the seller address. VAT Number ZATCA registration. Your Saudi VAT registration number. API Key ZATCA Fatoora portal. The API key issued by ZATCA. Zenoti stores this encrypted at rest. Host URL ZATCA Fatoora portal. The Fatoora API endpoint. Sandbox and production differ. Center ID Type ZATCA (see Seller registration types). Commercial registration number, Momra license, MLSD license, Sagia license, or Other license. Center ID Number Your own registration documents. The seller identification that pairs with the chosen type. Username, Password ZATCA Fatoora (optional, used where ZATCA requires basic auth alongside the API key). Credentials only if ZATCA issued them. Zenoti stores the password encrypted at rest. Select Save.
Worked example: A spa center in Riyadh with Commercial Registration has: Org Legal Name = their trade name exactly as ZATCA has it registered, VAT Number = a 15-digit number starting with 3, Center ID Type = Commercial registration number, Center ID Number = the 10-digit commercial register number, and Host URL = the production Fatoora API endpoint provided by ZATCA (sandbox would be a different URL used only for testing).
Configure invoice settings
- Still in the Zatca e - Invoicing accordion, locate the invoice settings section.
- Set the default invoice type for each center. For spa / salon / medical centers that serve primarily individual consumers, B2C is the typical default. Centers serving corporate / VAT-registered buyers default to B2B.
- Turn on Sending Receipt Number to ZATCA only if your reconciliation process relies on a non-invoice receipt number alongside the invoice number. Turning it on reveals the zero-value settings.
- Set the Receipt sequence number for zero-value invoices (used for fully-discounted or zero-total submissions).
- Select Save.
Enable per center
- For each Saudi center, select the center in the scope selector and expand Zatca e - Invoicing on Configuration > Integrations > Integration Settings.
- Turn on ZATCA e-invoicing for the center.
- Verify the center's bilingual legal name, VAT number, building number, district, and address match ZATCA records β both English and Arabic values must be present.
- Select Save.
Important: Enabling a center before all bilingual fields are complete will result in submission rejections. Complete all bilingual fields first.
How it works
- A service is completed and an invoice is created in Zenoti.
- At closure, Zenoti determines the document type:
- Default B2C invoice if no buyer VAT is present.
- B2B invoice if the buyer VAT number is captured.
- Credit note (B2B or B2C) if the invoice references a parent invoice (refund flow).
- Debit note for upward corrections (see Refunds, credit notes, and debit notes).
- Zenoti formats the payload in ZATCA's UBL schema with bilingual fields and VAT category codes (for example, "S" for standard 15%, "O" for out-of-scope with exemption reason "VATEX-SA-OOS").
- Zenoti submits to the Fatoora API with the
x-api-keyheader. - ZATCA validates, applies a cryptographic stamp, and returns a compliance response including the QR code.
- Zenoti stores the stamp, QR code, and compliance status with the invoice. The receipt printed for the guest includes the QR code, which can be scanned to verify the invoice on ZATCA's verification app.
Failure paths
| Failure mode | User-visible symptom | Resolution |
|---|---|---|
| Fatoora unreachable. | Closure fails with a network error. | Verify outbound HTTPS to the Fatoora host URL. If ZATCA is undergoing maintenance, wait for recovery. The invoice remains open β there is no automatic retry. |
| Authentication failed. | 401 / unauthorized. | Re-enter the API key. Request a new key from ZATCA if the previous one was rotated or revoked. |
| Buyer VAT missing (B2B invoice). | ZATCA rejects the submission citing the missing field. | Collect the buyer VAT and re-submit, or confirm the invoice should be B2C (downgrade would require voiding and re-issuing). |
| Arabic field missing (seller or buyer). | ZATCA rejects citing the missing Arabic translation. | Update the center or buyer record with the Arabic value and retry. |
| Signature / cryptographic validation failure. | ZATCA rejects the stamp. | Typically indicates a credential or clock-skew issue. Contact ZATCA support and verify the server time is accurate. |
| Duplicate submission. | ZATCA returns a duplicate document error. | Check the compliance log. If the original succeeded, the duplicate error is benign β do not reissue. |
| Schema version mismatch (ZATCA updated UBL schema). | Validation errors on fields that previously worked. | Contact Zenoti Support. |
| Invoice in a state ZATCA does not accept (for example, zero-value without prefix). | Rejection citing the invalid document configuration. | Configure the zero-receipt prefix, or use a nominal-value workflow. Confirm with your tax advisor. |
Edit or cancel a submitted invoice
Once ZATCA has accepted and stamped an invoice, the fiscal record is immutable. ZATCA does not permit editing or deletion of a submitted invoice.
| Invoice state | What you can do |
|---|---|
| Open in Zenoti, not yet submitted | Edit freely. No fiscal record has been created. |
| Submitted to ZATCA and stamped | Cannot be edited. To reverse, issue a credit note referencing the original invoice. To increase the amount, issue a debit note. To replace, issue both a credit note (reversing the original) and a new invoice (with corrected details). |
| Submitted but rejected by ZATCA | No fiscal record exists. Fix the rejection cause and resubmit. |
| Closure attempted but network failure | Retry closure once connectivity is restored. |
Refunds, credit notes, and debit notes
ZATCA handles reversals and adjustments via dedicated document types β refunds are never implemented as edits to the original.
| Zenoti action | ZATCA side | Reconciliation note |
|---|---|---|
| Full refund of a B2C invoice. | A B2C credit note is issued referencing the original invoice. Negative amounts. | Both documents appear in the ZATCA ledger. |
| Full refund of a B2B invoice. | A B2B credit note is issued. | Both documents appear in the ZATCA ledger. |
| Partial refund (B2B or B2C). | A partial credit note referencing the original. | The original retains its full amount. |
| Upward correction (additional charge on an existing invoice). | A debit note is issued referencing the original. | Appears in the ZATCA ledger alongside the original. |
| Void before submission. | No ZATCA document is issued. | Handle as a Zenoti-side cancellation. |
Train staff that credit notes and debit notes are their own ZATCA documents β they will appear as distinct entries in the Fatoora portal and on reports, paired by parent invoice reference.
Reconciliation
| Source | What to match on | Cadence |
|---|---|---|
| Zenoti: Collections by Invoices report, filtered to Saudi centers. | Zenoti invoice number. | Daily. |
| ZATCA Fatoora portal: invoice list. | Zenoti invoice reference and seller VAT number; for credit/debit notes, the parent invoice reference. | Daily. |
Any Zenoti submission that shows success in the compliance log but is not present in Fatoora within a working day should be escalated to ZATCA support. Zenoti's log shows what was sent and the response β the authority's portal is the ultimate record.
Tips
- Always test in the Fatoora sandbox before pointing Zenoti at production. Test the full set: B2B invoice, B2C invoice, credit note, and debit note.
- Audit every center's bilingual address once before go-live. Missing Arabic values cause silent rejections that staff won't notice until month end.
- Keep a scanner handy. ZATCA's QR code on the receipt can be verified via ZATCA's public verification app β a good staff training exercise.
- Server clock accuracy matters for cryptographic stamps. Ensure NTP is configured on any on-premise infrastructure.
- Maintain a log of your ZATCA API key rotation schedule. If ZATCA rotates or expires the key, submissions fail immediately at the next invoice closure.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Every invoice at a center fails to close with a ZATCA error immediately after enabling the integration. | API key or Host URL entered incorrectly. | Return to Configuration > Integrations > Integration Settings > Zatca e - Invoicing for the center, verify the API Key and Host URL against your ZATCA Fatoora credentials, and select Save. |
| B2C invoices submit but B2B invoices are rejected with a missing-field error. | Buyer VAT number not captured at the point of sale. | Train front-desk staff to enter the guest's or business's VAT number before closing B2B invoices. The field must be populated before closure β ZATCA does not allow post-submission correction. |
| Rejection errors reference Arabic field names you cannot locate in Zenoti. | Center's address or legal name is missing the Arabic translation. | Navigate to the center's profile and verify that all address fields (building number, district, city, region) and the legal name have Arabic values. |
| ZATCA stamps the invoice but the QR code does not print on the guest receipt. | Receipt template is not configured to include the ZATCA QR code field. | Contact Zenoti Support to verify the receipt layout for the center includes the ZATCA QR code element. |
| Fatoora portal shows a duplicate document error for an invoice you know was successfully stamped. | A retry was submitted after the first successful acknowledgement was received. | Check the ZATCA compliance log in Zenoti. If the original submission shows success, the duplicate is benign β do not reissue the invoice. |
| Invoices submit successfully in sandbox but fail in production. | Production and sandbox have different Host URLs and API keys. | Confirm that the Host URL and API Key in Zenoti match the production credentials issued by ZATCA, not the sandbox credentials. |