How ERPNext supports KSA VAT reporting and where it stops
A Saudi finance lead who needs the KSA VAT report and a compliant tax invoice from ERPNext should first confirm which parts of the workflow ERPNext documents. The KSA localization creates KSA VAT Settings automatically when the first company with a Saudi address is set up, maps Item Tax Templates and accounts to the titles the KSA VAT report shows for VAT on sales and purchases, and provides a KSA VAT Invoice print format for Sales Invoices. Those three components are the starting point for the configuration. The localization also moved out of the core application: the ERPNext version 15 migration guide lists KSA localization among the features split into separate apps. Confirm which app carries the localization in the exact ERPNext version you will run, and whether it is installed on your bench or image, before you plan any mapping work. The ERPNext KSA VAT documentation describes the expected setup for each component.
DeployOpen prepares the configuration, the test data, the report walkthroughs and the evidence that the configuration behaves as documented. It does not file returns, issue certifications or confirm that an invoice satisfies ZATCA requirements. Those decisions sit with your organization, your tax advisor and the authority itself. Before go-live, ask your tax advisor to confirm which VAT treatments apply to your supplies, which invoice fields and invoice types are required, and how the report lines map to the return you file. Then compare that list against what the print format and the report actually produce, with your own sample invoices. Any gap between the documented behavior and your filing rules is yours to close, either through configuration, a custom print format or a documented manual step.
Plan for the places where ERPNext's defaults will not match your business. Item Tax Templates and account mappings need an owner who understands both the chart of accounts and the VAT treatment of each item group, and every change to them should be tested on a copy of production data. Custom fields or scripts added to meet a ZATCA requirement fall under your change control, so record who approved them and when. Review the localization again whenever you upgrade ERPNext or its companion apps, because a major version move can change where the mappings live. Ask your implementation partner for a written list of what was configured, what was tested and what remains your responsibility.
Mapping KSA VAT reporting requirements to ERPNext settings
This table maps each KSA VAT reporting requirement to the ERPNext capability that covers it, the configuration it needs, and who should own it. Read it as a checklist for the implementation team, and treat any row marked as a point to confirm as an open question to settle with your tax adviser and the ERPNext version you plan to run.
| Requirement | ERPNext capability | Configuration needed | Owner |
|---|---|---|---|
| KSA VAT report on sales and purchases | KSA VAT report covering VAT on sales and VAT on purchases, built from the KSA VAT Settings | Confirm the company is set up for Saudi Arabia so KSA VAT Settings is created with the first company; review the generated settings before first use | Finance lead with tax adviser |
| Item tax template mapping to report titles | Item Tax Templates and accounts mapped to the titles shown in the KSA VAT report | Create item tax templates for each VAT rate, assign the correct sales and purchase accounts, and map each to its report line | Finance systems owner |
| Accounts behind each report line | Report lines pull from the accounts linked to the templates | Check that each VAT account in the chart of accounts is used by one template only; document the mapping for auditors | Accountant |
| KSA VAT invoice print format | KSA VAT Invoice print format available for Sales Invoices | Select the KSA VAT Invoice format in print settings; test a sample invoice against the content your tax adviser requires | Finance lead with ERP administrator |
| Version 15 app dependency | KSA localization moved to a separate app in the version 15 migration | Confirm which app supplies KSA localization for your ERPNext version and install it before expecting the report and print format; point to confirm with the migration guide | ERP administrator |
| Requirements not covered by the documentation | No documented capability in the KSA VAT source material for these items | Confirm with the ZATCA specifications and your tax adviser before go-live; do not assume the report or invoice meets them | Compliance lead |
Configuration sequence before the first KSA VAT report
This sequence takes a Saudi company from a working ERPNext install to a tested KSA VAT report and invoice print format. Each step builds on the one before, so the report can be trusted before the first filing period.
Confirm the ERPNext version and KSA app
Your ERP administrator confirms the ERPNext version running on the target site and checks that the KSA localization app is installed on the same bench. The ERPNext version 15 migration guide lists KSA localization among the features moved into separate apps, so a version 15 or later site needs that app added explicitly. Done means the app appears in the installed apps list for the site and the version matches what your implementation partner tested against. Confirm the exact app name and supported versions with your Frappe release notes before you proceed.
Verify the automatic KSA VAT Settings
When the first company with a Saudi country setting is created, ERPNext creates KSA VAT Settings automatically. Your finance lead opens that document and confirms it is linked to the correct company and that the settings match the company's registration and reporting setup. Done means the settings record exists for each Saudi company and no company is missing one. If the record is absent, check the company's country and creation order before adding anything by hand.
Build item tax templates and accounts
Your finance team creates Item Tax Templates for each VAT treatment your products and services need, along with the tax accounts they post to on sales and purchases. The chart of accounts should separate output VAT on sales from input VAT on purchases so the report can read each side. Done means every taxable item group has a template, and each template points to accounts with the right account type and company. Confirm the treatment rates and categories with your tax adviser, since ERPNext does not decide them for you.
Map templates to report titles
In KSA VAT Settings, your finance lead maps each Item Tax Template and its accounts to the titles shown in the KSA VAT report, covering VAT on sales and VAT on purchases. This mapping decides which ledger amounts land in which report line. Done means every template in use is mapped to a title, and no template is left unmapped. Keep a written mapping table so your auditors and reviewers can trace each report line back to its accounts.
Test with sample sales and purchase invoices
Your finance team creates sample Sales Invoices and Purchase Invoices on a test site, using each tax template at least once and including at least one purchase with input VAT. They then run the KSA VAT report and compare each line with the figures calculated by hand from the same invoices. Done means every report title matches the expected totals, and any difference is traced to a template or account mapping and fixed. Use test data only, and record the results so the configuration can be approved before live use.
Review the KSA VAT invoice print format
The KSA VAT Invoice print format is provided for Sales Invoices. Your finance lead prints a sample invoice from the test site and checks that the company name, tax identifiers, item lines and VAT amounts display as your invoicing rules require. Done means the printed output has been signed off by finance and compliance against your own invoice requirements. Confirm with your tax adviser or the relevant authority which fields must appear before you make this format the default.
Evidence the KSA VAT configuration produces for reviewers
A KSA VAT setup is only as defensible as the records behind it. The items below are what a reviewer, auditor or tax adviser can ask to see, and each one should be kept under the same change control as the rest of your ERPNext configuration.
KSA VAT Settings record
Export and version the KSA VAT Settings record that ERPNext creates with the first Saudi company. It holds how the report titles map to accounts, so a reviewer can see which ledger accounts feed each VAT line. Record who changed it, when, and why, and compare it against the exported copy at each filing period. Any change after a return has been filed should be treated as a finding to explain.
Item tax template and account mapping
Item Tax Templates and their accounts determine how each sale and purchase lands in the report. Keep a dated list of every template, the rate it carries, and the account it posts to, and confirm that each sales and purchase template in use appears in that list. Review the list whenever a new item group or tax category is added, because an item without a template will not be classified the way you expect.
KSA VAT report output for each period
Save the KSA VAT report output for every filing period as a PDF or export, along with the date range and the company it covers. Compare the totals against the general ledger for the same accounts before filing. A saved report lets you show what was filed even if later postings or amendments change the live figures.
Sample KSA VAT invoices
Print a sample of Sales Invoices using the KSA VAT Invoice print format, covering standard-rated, zero-rated and exempt lines where your business has them. Keep these samples with the template version that produced them. Reviewers often check whether the printed fields match the invoice data stored in the system, so store one sample per template change.
Frappe and app version records
Record the ERPNext and Frappe Framework versions in use, along with the installed localization app and its version. ERPNext v15 moved KSA localization into a separate app, so a missing or mismatched app can change the report. Keep the record with each deployment, and tie each upgrade to its own change ticket and a repeat check of the report.
Change tickets for configuration edits
Link every change to the settings, templates, accounts and print formats above to a ticket that states the reason, the approver and the test run. Use the same process for any custom script or app that touches tax fields. Server Scripts in version 15 and later must be enabled explicitly, so record that setting as part of the change history as well.
How the mapping works between item tax templates and report lines
The KSA VAT report does not read tax rates directly from invoices. It groups amounts into fixed report lines on VAT on sales and VAT on purchases, and each line is filled from the accounts and item tax templates that ERPNext's KSA VAT Settings link to those titles. When ERPNext creates KSA VAT Settings with the first Saudi company, it provides the mapping framework, but the mapping is only as complete as the templates and accounts your company actually uses. Your first job is to list every Item Tax Template in use, including templates for standard rated, zero-rated and exempt supplies, and confirm that each one has a target in the KSA VAT Settings mapping.
An unmapped template produces an incomplete report, and the gap is easy to miss. Sales or purchase amounts that carry a template outside the mapping do not appear under the expected report title, so the totals can look plausible while the VAT figure is understated or overstated. The same risk applies to accounts: if a VAT output or input account sits outside the mapped set, the ledger will show tax that the report does not pick up. Reconcile the report totals against the VAT control accounts in your chart of accounts for the same period, and investigate any difference before the return is prepared.
Test this against your own chart of accounts, not against a demo company. Confirm which accounts your company uses for output and input VAT, whether any legacy accounts or templates from earlier configurations are still in use, and whether imported or migrated items carry templates that were never reviewed. Run a sample period with known invoices and purchase bills, trace each one into the report line, and keep the test evidence with the configuration record. The ERPNext KSA VAT management and reporting documentation describes the mapping titles to check against, and any template that cannot be placed should be resolved with your tax adviser before filing.
What ERPNext does not cover for Saudi VAT compliance
ERPNext produces the KSA VAT report and invoice layout, but the surrounding obligations sit with your company, your tax advisor and the authorities. The cards below list the gaps to confirm before you rely on the report for filing, so that each one has an owner and a documented answer.
Electronic invoicing requirements
The KSA VAT Invoice print format gives you a printed layout for Sales Invoices, but the facts available here do not establish how ZATCA e-invoicing works, which invoice types must be issued electronically, or what data must be submitted to the authority. Confirm the current e-invoicing requirements with ZATCA and your advisor, and decide whether the print format alone satisfies them or whether a separate integration is needed.
Filing and payment processes
ERPNext generates the KSA VAT report from posted ledger data, but it does not file the return or send payment. Confirm the filing frequency, the submission channel, the deadlines and the payment method for your company, and assign who prepares, reviews and submits each return. Record the steps in your close checklist so the report is reviewed before anyone files it.
Tax rates and classification decisions
The item tax templates and account mappings are only as correct as the rates and categories you assign. Items such as zero-rated, exempt or out-of-scope supplies need a documented decision, and the rules for each should come from your advisor. Review every template and item group before go-live, and keep a change log whenever a rate or classification changes.
Data retention and record keeping
ERPNext keeps the records it creates, but how long you must keep invoices, reports and supporting documents is a legal question for your jurisdiction. Confirm the retention period with your advisor, then check that your backup policy, storage and any archiving tools support it. Test that you can restore a past period and reproduce its VAT report.
Validation by a tax advisor
No ERPNext configuration replaces a review by a qualified Saudi tax advisor. Ask the advisor to test the KSA VAT report against a sample of real filed returns, check the print format against the invoice content they require, and sign off on the mapping of accounts. Keep their sign-off with the configuration records so that the decision trail is available to auditors.
Questions to answer before hiring help with KSA VAT in ERPNext
What drives the cost of KSA VAT setup in ERPNext?
The main drivers are the number of companies and branches, how many item tax templates and VAT accounts you already have, how complex your chart of accounts is, and how much testing against real invoices is needed before go-live. A single Saudi company with a clean chart of accounts and standard sales and purchase tax treatment is a smaller job than several companies with mixed VAT rates, multiple currencies or legacy tax codes. Ask any provider to price these items separately in a written scope so you can see which ones move the total. Hosting costs are a separate line. The ERPNext pricing page shows what self-hosting and Frappe Cloud cost, and it notes that implementation is available through certified partners.
Which ERPNext version do I need for KSA VAT reporting?
Confirm the version before you scope the work, because the Saudi localization is no longer part of the core ERPNext application after version 15. The ERPNext version 15 migration guide lists KSA localization among the features moved to separate apps, so you need to install and configure the matching app for your version. Check the ERPNext version 15 migration guide for the app name and install steps. Also check the Frappe supported versions page to confirm your version is still supported, since an unsupported version changes both the risk and the upgrade work.
Can my own team configure KSA VAT in ERPNext without a partner?
Often yes, if you have someone comfortable with ERPNext accounting and tax setup and the time to test. The configuration itself is mostly settings, item tax templates, account mapping and a print format, so the work is not primarily coding. The harder part is checking that each item, tax template and account lands in the correct line of the KSA VAT report on sales and purchases. Your team should be able to explain each mapping to your accountant and reproduce the report from known test invoices. If nobody on staff has done this before, a partner can shorten the learning curve, but you should still own the sign-off.
How long does KSA VAT setup take in ERPNext?
No fixed duration can be stated here because it depends on the number of companies, the state of your item and tax master data, and how many test cycles your finance team runs. The automatic creation of KSA VAT Settings with the first Saudi company removes some manual steps, but mapping templates and accounts and validating report totals usually takes the most time. Ask any provider for a timeline tied to specific milestones: settings and mapping, a test cycle on sample invoices, reconciliation of the report against the ledger, and go-live. A fixed-scope agreement should state these dates in writing.
What do finance and IT need to provide for the KSA VAT project?
Finance needs to supply the VAT treatment rules for each item and service, the accounts used for output and input VAT, a sample set of sales and purchase invoices, and a reviewer who can confirm the report figures. IT needs access to a test environment with the correct ERPNext version and apps, a route to install and update the localization app, and a change process for production. Both teams should agree who approves the mapping and who signs off the first live report before filing. Without a named finance owner, mapping decisions tend to stall during testing.
How do I ask for a fixed-scope quote for KSA VAT work?
Send a written scope that lists the companies, ERPNext and app versions, the number of item tax templates and accounts to map, the print format changes you need, the test invoices to be used, and the environments involved. Ask for deliverables, acceptance criteria and a timeline with milestones, and state who is responsible for tax rule decisions. A fixed-scope quote should say what is excluded, such as hosting, custom report changes or filing support. Request separate line items for setup, testing, training and any ongoing support, so you can compare providers on the same basis.
Does a partner help with the VAT return itself?
Set expectations first. A partner can configure ERPNext so the KSA VAT report is produced from your ledger and invoices, and can test that the figures match your records. DeployOpen prepares systems, controls and evidence for compliance work, but it does not issue audit reports or attestations, and the VAT return remains your responsibility. Confirm with your tax advisor which report fields, filing steps and retention rules apply to your company, and keep their sign-off as part of the acceptance criteria.
What a KSA VAT configuration engagement includes
A DeployOpen engagement for KSA VAT reporting starts with a written scope that names the versions and apps in play. We confirm which ERPNext version and Frappe Framework version the site runs, and whether the Saudi Arabia localization is installed as the separate app that ERPNext's version 15 migration guide describes, since that localization is no longer bundled with the core. The scope then covers a review of the KSA VAT Settings document that ERPNext creates with the first Saudi company, checking the company record, the default accounts and the reporting periods against the filing calendar your advisor provides. Each step names the person who signs it off and the environment where it runs, so nothing changes in production before it has been tested in a copy of your site.
The second part of the scope covers mapping and presentation. We review each Item Tax Template and the accounts behind it, confirm that the titles shown in the KSA VAT report for sales and purchases map to the right accounts, and document every mapping decision in the engagement record. The scope also includes configuring the KSA VAT Invoice print format for Sales Invoices, including the fields your invoices must show, and a set of test invoices covering standard-rated, zero-rated and exempt items, returns and purchases. Each test is run, reconciled to the report totals and kept with its expected result. Ask for the exact list of test cases and acceptance criteria in the written scope before work starts.
The engagement closes with an evidence pack: the version and app inventory, the settings and mapping records, the print format export, test invoices with their reconciliations, and the change log for any custom scripts or fields. This pack supports your tax advisor and external auditors, who make the compliance determination. DeployOpen prepares the system and the evidence, but it does not certify that your VAT filings meet Saudi requirements. Confirm with your advisor which rules apply to your business, and confirm with the Zakat, Tax and Customs Authority any filing or e-invoicing obligations that sit outside the ERPNext configuration.
How DeployOpen works on this
DeployOpen plans, implements and supports ERPNext inside your own infrastructure, including the KSA VAT configuration for Saudi companies. The work starts with a written scope that ties the VAT report to your actual tax codes, accounts and invoice flow, then moves through build, testing and handover.
How we scope
- Review your Saudi entities, sales and purchase tax templates, and the accounts behind each VAT line before any settings change
- Confirm with your tax advisor which report titles and item tax templates your filing depends on
- Agree the scope in writing with deliverables and timelines fixed before work begins, as most engagements are fixed-scope
How we build
- Verify the automatically created KSA VAT Settings against your company master data and chart of accounts
- Map each Item Tax Template and account to the matching KSA VAT report title, then test sample sales and purchase invoices
- Adapt the KSA VAT Invoice print format for Sales Invoices only where your approved invoice content requires it
How we hand over
- Deliver a written record of the mappings, test invoices, report reconciliations and any custom print format changes
- Walk your finance and tax staff through generating the KSA VAT report and checking it against ledger balances
- Document how new tax codes, accounts and company entities should be added under your change control
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after go-live
- Retest the KSA VAT mappings when you upgrade ERPNext or install the Saudi localization app on a new version
- Confirm with your tax advisor and the ERPNext release notes before each upgrade that filing requirements and report layouts still match
