Saudi Arabia¶
Modules¶
The following modules related to the Saudi Arabian localization are available:
Name |
Technical name |
Description |
|---|---|---|
Saudi Arabia - Accounting |
|
Default fiscal localization package for Saudi Arabia with Phase 1 QR code support. |
Saudi Arabia - Accounting Reports |
|
Accounting reports for Saudi Arabia |
Saudi Arabia - E-invoicing |
|
Enables ZATCA Phase 2 API integration for e-invoicing compliance. |
Saudi Arabia - E-invoicing (Simplified) |
|
Enables e-invoicing through PoS. |
Saudi Arabia - Point of Sale |
|
Adds compliance fields and behavior for PoS invoices. |
Saudi Arabia - Withholding Tax |
|
Forces the installation of the Withholding Tax on Payment module. |
Note
The localization’s core modules are installed automatically with the localization. The rest can be manually installed.
Localization overview¶
The Saudi Arabian localization package ensures compliance with Saudi Arabian fiscal and accounting regulations. It includes tools for managing taxes, fiscal positions, reporting, and a predefined chart of accounts tailored to Saudi Arabia’s standards.
The Saudi Arabian localization package provides the following key features to ensure compliance with local fiscal and accounting regulations:
Chart of accounts: a predefined structure aligned with Saudi Arabian regulations
Taxes: preconfigured tax rates, including standard 15% VAT, zero-rated, and exempt options
Fiscal positions (tax and account mapping): automated tax adjustments based on customer or supplier registration status
Withholding taxes: predefined withholding tax rules for applicable service categories
Tax reporting: automated tax reports
E-invoicing (ZATCA): integration for electronic invoicing in line with Saudi Arabian government requirements
Taxes¶
The Saudi Arabian localization includes preconfigured sales, purchase, and withholding taxes:
- Standard VAT (15%): The prevailing rate applied to the majority of goods and services supplied within the Kingdom.The supplier charges 15% VAT on the sale (Output VAT) and is generally entitled to deduct the VAT paid on its business purchases (Input VAT).
Example
Most commercial sales, retail goods, telecommunication services, non-exempt private education, and non-exempt private healthcare.
- Zero-rated VAT (0%): These are taxable supplies where the rate of tax applied is 0%.The supplier charges no VAT on the sale, but, critically, is fully entitled to recover the input VAT paid on costs related to making those supplies.
Example
Exports: Supplies of goods and services to a non-GCC resident or for consumption outside the Kingdom.
International transport: Services for the international transport of passengers and goods, and related services.
Specific goods: Supplies of qualifying medicines and qualifying medical equipment, as specified by ZATCA/Ministry of Health.
Residential property: First supply of a new residential building/property to a Saudi citizen, up to a value of SAR 1,000,000 (subject to specific conditions).
Investment metals: Qualifying gold, silver, and platinum of 99% purity or higher (supplied for investment).
- Exempt transactions: These transactions fall outside the scope of VAT, meaning they are not subject to the tax.The supplier does not charge any VAT on the sale and is not entitled to recover the input VAT paid on costs related to making these supplies (resulting in an unrecoverable cost).
Example
Financial services: interest on loans, provision of credit, operations of current/deposit/savings accounts, issuance or transfer of money or securities, and life insurance.
Real estate: bare rental (leasing) of residential property.
- Import VAT: VAT is levied on goods brought into the Kingdom from a non-GCC country.VAT is typically calculated at the standard rate (15%) and is paid to the Customs Authority at the point of importation.
Important
When assigning discounts to invoices, assign a 15% tax on the line containing a global discount to comply with ZATCA rules.
Reverse charge mechanism (RCM)¶
Description: Mechanism that shifts the responsibility for accounting for VAT from the non-resident supplier to the resident recipient of the goods or services.
Mechanism: The VAT-registered recipient must calculate and account for the VAT (as both output VAT and input VAT) in their VAT return. This typically results in a net zero effect on the VAT return, provided the input tax is fully deductible.
Application: Primarily used for B2B supplies of services from a non-resident supplier to a VAT-registered business in Saudi Arabia.
Withholding taxes¶
There are two available methods for calculating withholding tax: gross and deducted.
Gross withholding: This is the primary configuration, where the withholding amount is calculated in addition to the bill total. For example, if the total bill is entered as 115 SAR, the system calculates the base plus Withholding Tax (WHT) without reducing the payment amount.
Deducted withholding: It reduces the payable amount by the withholding amount directly, meaning the total payment reflects the deduction upfront. This affects how the accounting entries and payable lines are booked, as seen in the comparison screenshots provided.
Note
Deducted withholding taxes are not enabled by default. To activate it, go to Accounting –> Configuration –> Taxes and enable the relevant withholding tax.
The following Withholding Tax (WHT) configurations are preloaded and available for use:
5% Withholding Tax: Applied on payments for rent, dividends, technical and consulting services, air and maritime freight, as well as interest, insurance, and reinsurance premiums.
15% Withholding Tax: Applies to royalties and other general service payments made to non-residents.
20% Withholding Tax: Reserved for management fees and specific high-value service payments.
Tax reporting¶
The VAT and Withholding Return provide a detailed breakdown of taxable, zero-rated, exempt, and withholding transactions. Like other financial reports, the VAT and Withholding Return can be filtered by period, compared against other periods, and exported in Excel and PDF formats, ensuring compliance with Saudi Arabia tax laws.
Company and contacts¶
To ensure proper integration with ZATCA, the following fields are required on the company record:
Company Name (must match exactly VAT certificate)
All relevant Address fields, including the District, Building Number, and Plot Identification
Identification Scheme
Tax Identification Number
Commercial Registration Number
Momra License
MLSD License
700 Number
Sagia License
VAT Number
Currency must be set to SAR.
Important
All fields must be completed accurately to avoid rejection during ZATCA onboarding.
Note
The same configuration applies to all relevant contact forms.
Branches configuration¶
Set up your company branches in compliance with ZATCA rules.
Important
On the branch contact form, enter the same VAT Number as the parent company and enter the branch Commercial Registration Number (CRN) in the Identification Scheme field.
Note
Either use the parent company’s sales journal to follow a centralized billing system model, or onboard a new branch-specific journal to set up a multi-threaded system with parallel invoice processing.
Invoicing language¶
Invoices can be issued in different languages to meet regional or customer-specific requirements at two levels:
Customer level: To assign a preferred language to a customer, go to or , and open the relevant customer form. In the Language field, update the language. All documents are then automatically generated in the selected language for that customer.
Important
Saudi Arabia’s VAT regulations require Tax Invoices and Simplified Tax Invoices (along with corresponding credit notes or debit notes) to be in Arabic, mandatorily. Invoices can be bilingual, including English.
Company level: To add Arabic as a secondary language to meet Saudi Arabia VAT regulations:
For Tax Invoices: Go to , in the Fiscal Localization section.
For Point of Sale receipts: Go to , and navigate to the Bills & Receipts section.
Then, enable the Gulf Cooperation Council Format option, and Save.
Electronic invoicing with ZATCA¶
The ZATCA e-invoicing system is designed to streamline and digitize the invoicing process for businesses operating in Saudi Arabia.
ZATCA Phase 2 employs a clearance e-invoicing model for Business-to-Business (B2B) transactions. Conversely, for Business-to-Consumer (B2C) transactions, Odoo generates a QR code and subsequently reports these transactions to the Fatoora reporting endpoint.
In a B2B scenario, a Tax Invoice is issued, whereas in a B2C scenario, a Simplified Tax Invoice is generated.
See also
Step-by-step process¶
When onboarding to ZATCA (Phase 2), there are three modes:
Sandbox: Common pre-configured testing environment; use it to simulate integration functionality out of the box.
Simulation (Pre-Production): User-specific testing environment; use it to simulate your unique integration.
Production: Live environment
Sandbox¶
Tip
Use VAT Number 399999999900003 on your company setup for sandbox testing.
- Set the databaseGo to and, in the Saudi Arabia Electronic Invoicing section, ensure the ZATCA API mode is set to Sandbox.
- Company information verificationMake sure all company information is complete.
Onboard sales journals
Go to .
Open the Sales journal.
Under the ZATCA tab, click Onboard.
In the Enter the OTP window, the 6-digit OTP is pre-populated. Click Confirm.
Invoice testing
Once the invoice is confirmed, a blue banner appears; click Process now.
Ensure the response from the API is Action Successful. If not, review the API response displayed in the chatter and take the appropriate actions.
Simulation (Pre-Production)¶
Set the database
Duplicate your Live/Production database.
Go to and, in the Saudi Arabia Electronic Invoicing section, ensure the ZATCA API mode is set to Simulation (Pre-Production).
- Company information verificationMake sure all company information is complete.
Onboard sales journals
Go to .
Open the Sales journal.
Under the ZATCA tab, click Onboard.
In the Enter the OTP window, enter the 6-digit OTP retrieved from the Fatoora Simulation Portal under the Testing Environment. Then click Confirm.
Invoice testing
Once the invoice is confirmed, a blue banner appears; click Process now.
Ensure the response from the API is Action Successful. If not, review the API response displayed in the chatter and take the appropriate actions.
Note
Simulation (Pre-Production) mode invoices are not legally valid.
Production¶
- In your Live/Production databaseGo to and, in the Saudi Arabia Electronic Invoicing section, ensure the ZATCA API mode is set to Production.
- Company information verificationMake sure all company information is complete.
Onboard sales journals
Go to .
Open the Sales journal.
Under the ZATCA tab, click Onboard.
In the Enter the OTP window, enter the 6-digit OTP retrieved from the Fatoora Portal under the Production Environment. Then click Confirm.
Invoice synchronization
Once the invoice is confirmed, a blue banner appears; click Process now.
Ensure the response from the API is Action Successful. If not, review the API response displayed in the chatter and take the appropriate actions.
Note
Each Sales journal must be onboarded separately.
If a sales journal is no longer needed as a ZATCA solution unit, make sure to revoke it in your Fatoora portal. To do so, click View List of Solutions And Devices, select the relevant solution and device under Revoke CSID, then click Revoke and Confirm.
Warning
Once the API mode is switched to Production and an invoice is submitted to ZATCA, it cannot be changed back to Sandbox or Simulation (Pre-Production).
OTP’s generated from either the Fatoora Simulation or Production portal expire after 60 minutes and need to be regenerated.
Invoice submission to ZATCA¶
After submitting the invoice to ZATCA, a structured response message is returned by the API in the chatter.
Example
[202] BR-KSA-F-13 : [BR-KSA-F-13] - Please recheck Other Seller/Buyer ID (BT-29 or BT-46) as it contains an invalid value.
Common codes that can be received:
Code |
Action |
|---|---|
200 – Action Successful |
No action required. |
202 – Action Successful (with Warnings) |
|
303 – Clearance Switched Off |
Submit the invoice through the reporting flow instead of clearance. |
400 – Action Failed (Rejected) |
Review the detailed error message, correct the issue, and resubmit. |
401 – Unauthorized |
|
413 – Payload Too Large (Invoice Not Received) |
Reduce the invoice payload size and resend. |
429 – Too Many Requests (Invoice Not Received) |
Resend the invoice. |
500 – Internal Server Error (Invoice Not Received) |
Resend the invoice. |
503 – Service Unavailable (Invoice Not Received) |
Resend the invoice. |
504 – Request Timed Out (Invoice Not Received) |
Resend the invoice. |
The color of the message displayed in the chatter after an invoice is confirmed and submitted indicates the following information:
Green: invoice successfully accepted - The invoice is fully compliant and has been successfully validated by ZATCA.
Yellow: invoice accepted with warnings - The invoice is legally valid but was accepted with a warning. The issue should be reviewed and corrected for future submissions.
Red: invoice was rejected - The invoice was not accepted by ZATCA and is not legally valid. It must be corrected and resubmitted.
If the invoice is rejected, an error message is displayed in the invoice’s chatter. Correct the underlying issue described in the message description in the invoice or company settings. Then, to resubmit the invoice, click Retry.
Important
Invoices rejected by ZATCA remain in a Rejected state and are not considered legally valid.
In case of any incidents, technical errors, or emergency matters that prevent the generation of e-invoices/e-receipts, notify ZATCA. Once the issue has been resolved, contact ZATCA again using the same communication channel. For specific failure scenarios, refer to the steps outlined in ZATCA’s guidelines (page 45).
QR code verification¶
To verify the QR Code on the invoice, scan it using the official ZATCA app.
Once in the app, click Services. In the E-Invoice Validation section, click Start Service. Then, begin scanning the invoices’ QR codes.
Note
The QR verification output does not display a currency symbol. The invoice amount is always shown as a plain numeric value, irrespective of the currency used.
An invoice with a related contact (e.g., Invoicing Address) is sent to the clearance API (B2B).
Debit and credit notes¶
To create a credit or debit note, include a ZATCA-approved reason from the ZATCA Reason field in the Credit/Debit window, as required by ZATCA regulations:
Cancellation or suspension of the supplies after their occurrence, either wholly or partially.
Essential change or amendment in the supply that results in a change to the VAT due.
Amendment of the supply value that was pre-agreed between the supplier and the consumer.
Goods or services refund.
Change in the seller’s or buyer’s information.
Tip
The ZATCA Reason field is also available in the credit/debit note Other Info tab.
Note
Whenever the credit/debit note is unrelated/independent, fill in the sequential number of the original invoice(s) that the credit/debit note is related to in the Customer Reference field.
Down payments (advance payments)¶
Handle down payments (advance payments) in compliance with ZATCA’s guidelines.
Retention¶
Retention is an amount temporarily held by the customer, defined by the commercial contract, to ensure the quality and completion of the work. It is usually a percentage of the invoice value (e.g., 5-10%) and serves as security against future defects; it is ultimately paid back to the contractor once the warranty period expires.
For ZATCA, the commonly applied rule is that VAT is calculated based on the full invoice amount, even if the customer withholds a portion as retention. ZATCA advises taxpayers to first determine the tax position, specifically whether the retention amount reduces the taxable amount or not. Tax position depends on contractual terms.
The Odoo retention workflow ensures, through tax position, that the retention amount does not reduce the taxable amount.
Note
Any negative tax (e.g., -20%) configured with the Is Retention checkbox enabled has no impact on the UBL 2.1. It only applies when this retention tax is used in conjunction with a generic tax (e.g., 15%) on the invoice line and represents a percentage of that invoice line. For example, if a taxpayer wants to retain 20% of the invoiced goods, both the 15% tax and the -20% retention tax would be applied to the invoice line.
Within this same tax position, retention can also be applied at the invoice level as an separate negative invoice line using a 0% (Not Subject to VAT) tax rate.
Warning
Using a negative tax with Is Retention enabled, along with a generic tax on the invoice line, usually indicates that VAT has been paid on the full taxable amount. Therefore, the final invoice for releasing the retention amount does not qualify as a Tax Invoice and should not be submitted to ZATCA.
The 0% (Not Subject to VAT) tax is already preconfigured according to ZATCA rules; do not modify it.
Important
When creating a new retention tax, create a Retention tax group and assign it to this newly created retention tax to comply with ZATCA rules.
To add the Retention Amount as a note on the invoice line, click Add a note to comply with ZATCA rules. For example - Retention Amount:
[retention amount] SAR
Generated documents¶
Once an invoice is submitted, a UBL 2.1 XML file is generated and sent to ZATCA API endpoints. For auditability, this XML file is stored in the chatter. To display it, click the (attachments) icon.
Additionally, the invoice PDF generated when using Send is displayed in the chatter. Both the XML and PDF files are permanently attached to the invoice and cannot be deleted to ensure compliance with ZATCA regulations.
Important
Successfully ZATCA-submitted invoices can only be reset to draft in Sandbox or Simulation (Pre-Production) modes.
Tip
To automatically generate a PDF/A-3 with the embedded UBL 2.1, click Send.
Point of sale¶
ZATCA integration configuration¶
Note
Make sure the Saudi Arabia - E-invoicing (Simplified) (l10n_sa_edi_pos) module is installed.
PoS orders must be properly reported in compliance with ZATCA Phase 2. To do so, follow these steps:
Onboard the Invoices default journal in the PoS settings:
Go to . In the yellow banner, select the relevant Point of Sale, then navigate to the Accounting section.
In the Default Journals section, find the Invoices field and click the (right arrow) to open the default Sales journal.
Under the ZATCA tab, click Onboard.
In the Enter the OTP window, enter the 6-digit OTP retrieved from the Fatoora Portal under the Production Environment. Then click Confirm.
Assign a customer to the order before finalizing the transaction.
These steps ensure that each receipt is processed as a compliant e-invoice and reported to the ZATCA portal in real time. Once the receipt is generated, the Phase 2 QR code automatically appears on both the printed receipt and the PDF.
