Subscribe Us

Please fill in your details and we will share updates with you on a regular basis

Name
ISD Code
Phone Number
Company Name
Thank you for your interest. Our experts will contact you soon.
Oops! Something went wrong while submitting the form.

Stay updated with all the latest
announcements from ZATCA

ZATCA Updates

SDK update 3.4.1

23rd Mar, 2025

New SDK version update released by ZATCA
ZATCA released a new SDK version 3.4.1 of the software development kit (SDK) on 23rd Mar, 2025 for the production and test environments.
The latest ZATCA SDK can be downloaded from: https://sandbox.zatca.gov.sa/downloadSDK.

Action required from you:

  • If you are using ClearTax APIs for E-Invoice generation, then there is no change required in your systems, as we will handle all the modifications
  • Please understand the new validation rules and amendments so that any warnings or errors in e-Invoice generation can be resolved quickly
  • We suggest updating to the latest SDK version at your PoS systems if the SDK is being used to generate E-Invoices offline from stores ,but since there are no major change,s it can be skipped
  • There will be no interruption to your business and E-invoicing operations

Below is a complete breakdown of the SDK update with details on the changes:

#

ZATCA Update

What was it before?

What does this update mean?

1
Amend the wording of the validation rule (BR-KSA-EN16931-06) to clarify that Charge on price level (BG-29) is not allowed. The value of Indicator can only be ' false'.
Wording of validation rule (BR-KSA-EN16931-06) - An indicator that this AllowanceCharge describes a discount/Charge. The value of this tag indicating discount (Allowance) must be "false".
There has been an amendment in the wording of the validation rule (BR-KSA-EN16931-06). The words now read “The value of Indicator can only be ' false”.
2
Remove Business rule (BR-KSA-86) from the set of validation to accept buyer's email id value without any restrictions on the format of email id.
There were no rules related to email addresses in ZATCA documentation but the format of email given was validated to check if the provided value in the e-Invoice request is as per the expected format. If it was not then an error message was returned.
Buyer email id will not be validated in the e-invoicing request. Buyer email could be passed in any format and there would not be any validation errors from ZATCA.

SDK update 3.4.0

3rd Mar, 2025

New SDK version update released by ZATCA
ZATCA released two new SDK versions of the software development kit (SDK) on 3rd Mar, 2025. The version is now updated from:
1. 3.3.9 to 3.4.0 for the production environment
2. 3.3.9 to 3.4.0 for the simulation/sandbox environment
The latest ZATCA SDK can be downloaded from : https://sandbox.zatca.gov.sa/downloadSDK.
Action required from you:

  • ClearTax systems will update to the latest version by 14th Mar
  • If you are using ClearTax APIs for E-Invoice generation then there is no change required in your systems as we will handle all the modifications
  • Please understand the new validation rules and amendments so that any warnings or errors in e-Invoice generation can be resolved quickly
  • We suggest to update to the latest SDK version at your PoS systems if the SDK is being used to generate E-Invoices offline
  • There will be no interruption to your business and E-invoicing operations

Below is a complete breakdown of the SDK update with details on the changes:

#

ZATCA Update

What was it before?

What does this update mean?

1
Introduced a new Business Rule (BR-KSA-98) to validate if the taxpayer has exceeded 24 hours to report a simplified invoice.
B2C invoices had to be reported to ZATCA within 24 hours as per the e-Invoice regulations but no validation or rule implemented during generation of e-Invoices.
The reporting datetime and issue date time will be checked and a warning message will be given in response if the difference between the times is more than 24 hours. Please ensure that B2C e-Invoices are reported within 24 hours to ZATCA.
2
Amend the Validation for the Item name (BT-153) field.
Item name or item description was validated to ensure whether it is present as it is a mandatory field but the contents were not validated.
Item name/description will be validated thoroughly to ensure compliance with the below parameters:
1. Item name in Arabic is mandatory.
2. Item name should not be in pattern/number (eg  1234 or abcd)
3. Item name should be minimum 3 characters.
3
Bug fixes for the validation rule (BR-S-08) when both two VAT rates (5% and 15%) for the Standard Rate VAT Category Code are included in the same invoice.
Receiving warning for E-Invoice data containing tax subtotals with both 5% and 15% tax rates in the standard-rated category.
Validation has been optimized to remove the warning if an invoice contains two tax subtotals with both 5% and 15% tax rates, provided that the calculations are accurate in the E-invoice data.
4
Updated error message for incorrect base64 encoded certificate.
Basic error message was given if the certificate or the encoding was incorrect.
A comprehensive error message will be given if the certificate value in the e-Invoice payload is incorrectly encoded or if the value is wrong.

SDK Update 3.3.8 and 3.3.9

28th Nov, 2024 and 10th Dec, 2024

New SDK version update released by ZATCA
ZATCA released two new SDK versions of the software development kit (SDK) on 28th Nov, 2024 and 10th Dec, 2024. The version is now updated from:
3. 3.3.7 to 3.3.8 and 3.3.9 for the production environment
4. 3.3.7 to 3.3.8 and 3.3.9 for the simulation environment
The new updates are within 15 days of each other. The latest ZATCA SDK can be downloaded from : https://sandbox.zatca.gov.sa/downloadSDK.
Action required from you:

  • ClearTax systems will update to the latest version by 03rd Jan
  • If you are using ClearTax APIs for E-Invoice generation then there is no change required in your systems as we will handle all the modifications
  • We suggest to update to the latest SDK version at your PoS systems if the SDK is being used to generate E-Invoices offline
  • There will be no interruption to your business and E-invoicing operations

Below is a complete breakdown of the SDK update with details on the changes:

#

ZATCA Update

What was it before?

What does this update mean?

1
Bug fixes the validation rules BR-CO-17 and BR-S-09 regarding the rounding issue in VAT Category Tax Amount (BT-117)
Warnings were given by ZATCA even when the rounding amount in the taxable amount field was correctly calculated and presented in the xml.
Incorrect warnings will not be returned by ZATCA irrespective of the value of the taxable amount. Any value given will be validated as per the VAT rule only and error/warning will be returned only in case of faulty calculations.
2
Introduced a new rule (BR-KSA-97) to ensure that if the Document Currency Code (BT-5) is present and different from "SAR," the value in "Invoice Total VAT Amount" (BT-110) must not be equal to the value in "Invoice Total VAT Amount in Accounting Currency" (BT-111)
VAT amount in document currency was not compared with the VAT amount in accounting currency irrespective of whether the currencies were same or different. All values given were accepted as it is without any errors or warnings.

SDK Update 3.3.5

Sep 16, 2024

New SDK version update released by ZATCA
ZATCA released a new version of the software development kit (SDK) on 16th Sept, 2024.
The version is now updated from:
5. 3.3.4 to 3.3.5 for the production environment
6. 3.3.4 to 3.3.5 for the simulation environment
The new update is within 15 days of the previous update 3.3.4. The latest ZATCA SDK can be downloaded from : https://sandbox.zatca.gov.sa/downloadSDK.
Action required from you:

  • ClearTax systems will update to the latest version by 04th Oct
  • If you are using ClearTax APIs for E-Invoice generation then there is no change required in your systems as we will handle all the modifications
  • We suggest to update to the latest SDK version at your PoS systems if the SDK is being used to generate E-Invoices offline
  • There will be no interruption to your business and E-invoicing operations

Below is a complete breakdown of the SDK update with details on the changes:

#

ZATCA Update

What was it before?

What does this update mean?

1
Fix the validation rule (BR-53) to not display as Warning when the Tax Currency Code (BT-6) equals to 'USD'
Warnings were given incorrectly in case VAT currency code was given as ‘USD’ but the VAT amount in accounting currency was not provided.
Validation rule on VAT currency code and VAT amount has been fixed to ensure that no warning is shown if the Tax Currency Code is given but VAT amount in accounting currency is not given.
2
Fix the validation rule(s) (BR-CO-17) and (BR-S-09) regarding to the rounding issue in VAT Category Tax Amount (BT-117)
ZATCA was giving incorrect warnings in case the value of taxable amount was equal to or greater than 1,000,000 even though all calculations were correct.
No incorrect warnings will be returned by ZATCA irrespective of the value of the taxable amount. Any value given will be validated as per the VAT rule only and error/warning will be returned only in case of faulty calculations.
3
Added new validation rules (BR-KSA-93), (BR-KSA-94), (BR-KSA-95), and (BR-KSA-96) to introduce Tax Exemption / Exception Reason Code (KSA-41) and Tax Exemption / Exception Reason Text (KSA-42) for document references of the prepayment invoice(s)
There were no validations related to Tax exemption Reason code and reason text for Z,E and O VAT categories passed in the document referencing prepayment invoices. Given values for adjustment invoices were accepted without returning any errors/warnings.
Validations have been added where the exemption reason code and exemption reason text will be checked for adjustment invoices referencing prepayment invoices. The values allowed are from the list of values specified by ZATCA depending on the VAT category codes. In case of incorrect values or absent exemption reason code/text, then warnings will be returned.
4
Added new validation rules (BR-KSA-91), and (BR-KSA-92) to introduce Company Legal Form (KSA-40) and Tax Point Date (BT-7) as the indicator for the B2G supplies and payment Order Date for Supply.
There was no way to identify whether a particular transaction is B2G supply or not and at which point the tax liability arises. 
ZATCA is introducing a new form validation to identify the legal structure of the company which would be helpful in identifying a B2G Supply. Also new fields have been introduced to identify the point at which the tax liability arises. More clarity is expected from ZATCA with examples.
5
Update the validation message regarding the QR code generation in case of an invalid / absent Invoice Issue Time (KSA-25)
The error message from ZATCA in case of missing or wrong issue time only highlighted the absent ‘Invoice Issue Time’.
The validation message related to missing or incorrect invoice time has been updated to explain the error with the correct expected format of ‘Invoice issue time’.

New SDK version update released by ZATCA

Sep 9, 2024

#

ZATCA Update

What was it before?

What does this update mean?

1
Amend the validation rule (BR-KSA-80) to sum up the Prepayment VAT Category Taxable Amount (KSA-31) and Prepayment VAT Category Tax Amount (KSA-32) for prepayment invoice lines regardless of whether the Pre-Paid amount (BT-113) is provided or not.
Validation was only done in instances where a prepaid amount was presented. Only if the prepaid amount was given then, the prepaid amount required to be equal to the aggregate of the VAT Category Taxable Amount and the Prepayment VAT Category Tax Amount.
The validation rule (BR-KSA-80) will be executed irrespective of whether the Pre-Paid amount (BT-113) is included or absent in the E-Inv data. The prepaid amount has to be calculated by summing the Prepayment VAT Category Taxable Amount and the Prepayment VAT Category Tax Amount for all prepayment invoice lines. Any errors in the calculation would result in failures/warnings.
2
Amend the validation rule (BR-KSA-79) on Prepayment VAT Category Tax Amount (KSA-32) to ensure that the rule applies even if the Pre-Paid amount (BT-113) is not provided.
Validation was only done in instances where a prepaid amount was presented. Only if a prepaid amount was given then, Prepayment VAT Category Tax Amount must be Prepayment VAT category Taxable Amount (KSA-31) x Prepayment VAT rate (KSA-34) /100.
The validation on the Prepayment VAT Category Tax Amount will be executed irrespective of the presence of the Pre-paid amount in the invoice data. Errors in the calculation of the Prepayment VAT category tax amount would result in failures/warnings.
3
Amend the validation rule (BR-KSA-CL-14) to increase length of the invoice QR Code (KSA-14) to be up to 1,000 characters instead of 700 characters.
E-Invoices with length of the QR code field greater than 700 characters would fail with a validation error. QR code is generated using seller, buyer and invoice details. Invoice details had to be trimmed to shorten the QR code and make it under 700 characters otherwise invoices would fail.
The accepted length of the QR code has been increased from 700 to 1,000 characters. Now invoices with long seller, buyer and item details can be generated without making any changes to the actual invoice information.
4
Fix bug for the validation rule (BR-KSA-EN16931-09), (BR-KSA-EN16931-08) and (BR-53).
Previously, ZATCA issued warnings requiring that if a VAT accounting currency code is specified, the invoice must also include the total VAT amount in the accounting currency.
Going forward no warnings will be returned in the response if the accounting currency and document currency are same i.e. SAR but one of the total VAT amounts is not given.
5
Fix bug for validation rule (BR-S-01) to be added to the set of validations applied to VAT category code of items (BT-151, BT-95, or BT-102)
BR-S-01 validation was previously not done by ZATCA and no warnings were returned.
If the document contains a line item with VAT category ‘S’ i.e. standard rated then there must be at least one tax subtotal for VAT category ‘S’. If the tax subtotal object is not present then warnings will be returned by ZATCA in response.
6
Amend the validation rule (BR-KSA-CL-04) to add a new code, “VATEX-SA-DUTYFREE", for VAT Exception reason code (BT-121) and add a corresponding VAT exception reason text, “Qualified Supply of Goods in Duty-Free area”, for VAT exception reason text (BT-120).
Previously, items sold in ‘DUTYFREE’ were not considered under exempt sales, and no separate exemption reason and code were present.
Sale of items from ‘DUTYFREE’ are now considered as part of exempt sales and the mentioned exemption reason code and text have to be provided during E-Invoice generation.
7
Update the SDK to support .Net Core 3.1 and .Net Core 8.0 to align with the latest version.
Previously, the SDK was not supporting .Net core 3.1 and 8.0
SDK is now compatible with both .NET Core 3.1 and .NET Core 8.0, ensuring it supports the most current versions. (Applicable Only in case if you are generating E-Invoice offline using .Net).
8
Upgrading .Net Framework from 4 to 4.8 to align with the latest version.
.NET Framework version was 4. 
Upgraded the .NET Framework from version 4 to version 4.8 to ensure compatibility with the most recent version. (Applicable Only in case if you are generating E-Invoice offline using .Net).
9
Add -version command to get the .NET SDK version.
Previously, the -version command was unavailable to check the .Net SDK version.
Incorporated the -version command to show the .NET SDK version.
10
Amend the validation for generating a (CSR) in a .NET application to accept both Arabic and English data, and to provide an error for any incorrect field.

Previously the .Net application was not accepting both Arabic & English data for CSR generation. Also, errors in data were not highlighted by the SDK during CSR generation
The certificate Signing Request (CSR) step in .NET SDK  application can accept data in both Arabic and English. It can also validate the data to flag errors when any field contains incorrect or invalid information.

ZATCA Issues with E-Inv generation on ClearTax Sandbox Resolved

Oct 5, 2023

The format of the timestamp in the UBL extensions part of the signed response has been changed due to which the response from ZATCA was not correctly captured.

Format of signing time earlier →
xades:SigningTime2023-10-05T05:45:33Z</xades:SigningTime>

Format of signing time new → xades:SigningTime2023-10-05T05:45:33</xades:SigningTime>
The character ‘Z’ at the end of the timestamp value was removed from the new response.

What was the impact?
All B2B/standard tax invoices going to the Clearance flow were impacted. The invoices were in ‘Pending’ status at ClearTax end with no QR code available in the response. Timestamp in the response is used to process multiple other flows which were all broken.

What action has been taken?
Change has been deployed from ClearTax side to accommodate the new format of timestamp on both sandbox and production. All new invoices that are attempted from 12 PM KSA time will be processed successfully.We have also reached out to ZATCA team on their developer community to understand more about the change.

What are the next steps?
ClearTax team will be retrying the invoices that were in ‘Pending’ status and update the entire response for those invoices. The reprocessing for all documents is expected to be completed by 5th October, end of day.
If some invoices have been retried multiple side from the taxpayer side without any change to any of the fields in the xml then ZATCA will consider it as one invoice only and not multiple.

What is required from the taxpayer side?
(i) Please refresh the ‘Documents’ page on the ClearTax web portal to check the latest status of the document as per ZATCA.
(ii) To get the latest status of the document on the ERP please retry the same invoice again or use the ‘Get Invoice’ API

New SDK version update released by ZATCA

May 23, 2023

New SDK version update released by ZATCA

May 17, 2023

ZATCA E-invoicing for Wave 3 & 4 customers announced

Apr 28, 2023

ZATCA announces the implementation of the 'Linking and Integration phase' for E-invoicing to start on 1 October 2023 and 1 November 2023, with the establishments that are selected within the third group and fourth group respectively.

Third group: Who does this effect?
Businesses based on the standard of the volume of revenues subject to VAT for the year 2021 or 2022 - whose revenues exceed 250M SAR

Fourth group: Who does this effect?
Businesses based on the standard of the volume of revenues subject to VAT for the year 2021 or 2022 - whose revenues exceed 150M SAR

ZATCA E-invoicing for Wave 2 customers announced

Dec 23, 2022

ZATCA announces the implementation of the 'Linking and Integration phase' for E-invoicing to start on 1 July 2023, with the establishments that are selected within the second group.

Second group: Who does this effect?

Businesses based on the standard of the volume of revenues subject to VAT for the year 2021 - whose revenues exceed half a billion riyals (500M SAR).

ZATCA Portal and APIs are going live

Dec 21, 2022

1- ZATCA Phase II production go-live
Starting Monday, Dec 26, 2022, ZATCA FATOORA portal will be available for go-live on production and you can start sharing invoices with ZATCA. Any invoices shared with FATOORA portal will be considered as official tax invoices as per the VAT Implementation Regulation and E-invoicing Regulation.

2- End of production testing for Phase II
ZATCA had allowed testing on the phase II production environment till now. This testing on the production environment will end on Friday, Dec 23, 2022. All invoices shared with ZATCA till Dec 23 will be purged by ZATCA. No invoicing will be allowed on ZATCA FATOORA portal or production APIs between Friday, 23 Dec 2022 and Monday, 26 Dec 2022.

3- New simulation environment by ZATCA for testing Phase II
A new simulation environment similar to the production environment will be set up by ZATCA on Tuesday, Dec 27, 2022. This simulation environment would mimic the production environment of ZATCA. More details about the simulation environment is to be shared by ZATCA and we will keep you posted on the updates.

What is ClearTax Readiness?
1. ClearTax will be ready for ZATCA go-live from Friday, Dec 23, 2022. We will be conducting a deployment Friday, Dec 23 between 4.30 AM to 6.30 AM KSA without any downtime or disruption of services.
2. In case you experience issues with ClearTax platform (for Phase I or Phase II) on Friday or thereafter, please reach out to your account manager or our support team at ksa-support@cleartax.in and we will resolve your issues at the earliest.

How does this affect ClearTax customers?

1- Customers who have completed UAT and are ready to go-live on Phase II Production-

  • Register all devices on ZATCA Phase II production environment starting Dec 26, 2022. Devices registered earlier would be purged and have to re-registered
  • Prepare for deployments in production environment for all ERP/ POS/ Billing systems
  • Coordinate with ClearTax account manager to get production URLs and Authentication tokens which need to be updated in the integration configuration
  • We recommend to keep 2-4 days timeframe dedicated for preparation and actual deployment

2- Customers who are in development or UAT stage for Phase II-

  • We anticipate that any testing with ZATCA Phase II may have to be paused from Friday, Dec 23 to Wednesday, Dec 28 till ZATCA sandbox environment is stabilized.
  • Coordinate with ClearTax account manager to get confirmation that the ClearTax sandbox environment (which is internally connected to the new ZATCA sandbox) is fully functional-
  1. ClearTax sandbox environment that connects to ZATCA sandbox environment is expected to be ready and available on Dec 24.
  2. ZATCA has provided Tuesday, Dec 27 as a timeline to set up their new simulation environment.
  3. ClearTax will try to complete set up and testing by Wednesday, Dec 28. Account managers will keep you updated if any delays are observed.
  • Post confirmation from account manager-
  1. Register all devices again on ClearTax sandbox environment
  2. Coordinate with account manager for changes in URL and authentication tokens (if any)
  3. Continue the development and testing on the sandbox environment

3- Customers who are using ClearTax Phase I and have not shifted to Phase II yet

  • We do not anticipate any changes for Phase I customers.
  • In case you experience issues with the ClearTax platform on or after Friday, Dec 23, please reach out to your account manager.

New SDK version update released by ZATCA

Dec 19, 2022

ZATCA announces the Cancellation of Fines and Penalties

Dec 1, 2022

To read more about the announcement, you can visit these links -
English: https://zatca.gov.sa/en/MediaCenter/News/Pages/news_976.aspx
Arabic: https://zatca.gov.sa/ar/MediaCenter/News/Pages/news_976.aspx

To read more about the announcement, you can visit these links -

EnglishArabic

New SDK version update released by ZATCA

Nov 6, 2022