Upgrading Odoo to version 20 in Bahrain and Saudi Arabia: method, localization checks and pitfalls

Odoo 20 was released in September 2026, and the same month Odoo 17 left standard support. For a company in Bahrain or Saudi Arabia, an upgrade is not only a technical conversion: the database carries VAT returns, ZATCA phase 2 certificates, Arabic invoice layouts and, often, a payroll that pays GOSI contributions and produces the WPS file. This guide sets out where each Odoo version stands, what Odoo’s upgrade service does and what stays your responsibility, the method we follow from the first test database to cut-over, and the Gulf-specific checks to run before you switch.

Where Odoo 17, 18, 19 and 20 stand in November 2026

Odoo releases one major version a year and supports each one for three years of standard support, on Odoo Online, Odoo.sh and on-premise alike. After that comes extended support, for an additional fee, available only on Odoo.sh (for a limited number of versions) and on-premise. The point that matters most: security updates are only provided during standard support. In between, Odoo publishes “SaaS” versions every two to three months (19.1 to 19.4 in 2026); they exist only on Odoo Online and have no extended support.

The Enterprise subscription agreement (version 13 of 24 September 2026) covers the three most recently released major versions, today 18, 19 and 20. For a database that stays on an older version, it provides that once a year, and no earlier than six months after the release of a new major version, Odoo may charge an extra fee equal to 25 % of the annualized subscription price. With Odoo 20 released in September 2026, a database still on Odoo 17 is exposed to that fee from March 2027 at the earliest.

Odoo’s upgrade service takes a database from any version to any major version still under standard support, or out of it for less than six months. A database on Odoo 16 or 17 can therefore go straight to 19 or 20 without stopping at the versions in between. Check that the target is open for your hosting before planning: on 2 November 2026, the request form on upgrade.odoo.com, used for on-premise databases, still offered 19.0 as its most recent target.

What Odoo’s upgrade service covers, and what stays yours

With an Odoo Enterprise subscription, upgrading a database to the most recent version is free, including the support needed to correct discrepancies in the upgraded database. Odoo’s service-level agreement is precise about the scope, and so is the subscription agreement: the service is a technical conversion of the database for the target version. Verifying and validating the result, and analyzing the impact of what changed, is the customer’s job.

An upgrade also does not cover going back to an earlier version, switching from Community to Enterprise, changing hosting type, or migrating from another ERP. And the subscription agreement lets the customer choose an Odoo Partner as its main point of contact for support and upgrades.

In a Gulf database, the line between the two columns usually runs through the localization layer: the Saudi and Bahraini modules are standard and Odoo converts them, but the bilingual invoice layout someone adjusted, the Hijri date on the delivery note, the WPS export for Bahrain or the bank file for a local bank are custom code, and porting them is part of your project.

The method, step by step

1. Inventory and freeze. List the version, the hosting, every module (standard, Studio, custom, third-party), the integrations (bank, e-commerce, EDI, APIs) and the modified reports and email templates. Odoo recommends freezing development, bug fixes aside, and challenging each customization against the release notes: what Odoo 20 now does as standard is removed rather than ported.
2. A first upgraded test database. Request it from the database manager (Odoo Online), from a staging branch (Odoo.sh) or with the command line or the upgrade.odoo.com form (on-premise). On-premise, the copy comes back without the filestore, which has to be merged with the production one. Read the upgrade report sent with it and posted in Discuss for administrators: views that broke during the conversion are deactivated and listed there.
3. Module porting. Each custom module must first install without errors on an empty Odoo 20 database, then run on the upgraded database, with upgrade scripts for renamed fields, models and identifiers. Do it in parallel with the first test database. On Odoo.sh, each commit on the upgrade branch restores the upgraded backup and updates the custom modules.
4. Functional test. Run complete flows: purchase, receipt, sale, delivery, invoice, credit note, payment, accounting reports, plus integrations, exports, automated and server actions, email templates and translations. Test databases are neutralized: scheduled actions are disabled, outgoing mail goes nowhere, payment providers and carriers are in test mode and bank synchronization is off. Standard defects go to Odoo support, which has a dedicated option for upgrade tests.
5. User acceptance. Key users run a real period in the test database: a month-end close, a VAT return, a payroll run, the invoices of a busy day. Then compare test and production on figures: trial balance at a date, receivables and payables, stock quantity and value, open orders.
6. Rehearsal and cut-over. Request fresh test databases regularly, since Odoo’s scripts and your data keep moving, and rehearse the full sequence the day before. Production is unavailable during the upgrade, and nothing entered after the copy is sent reaches the upgraded database, so stop data entry for the window.
7. Rollback plan. On Odoo Online, once the upgrade is complete it cannot be reverted. On Odoo.sh, the platform reverts a failed upgrade automatically and keeps a backup from before a successful one. On-premise, keep the old database, its filestore and the old code, and fix the go/no-go criteria and the deadline in advance: past that point, rolling back loses whatever was entered in the new version.

Gulf checks after the upgrade

The standard test checklist does not know about the NBR, ZATCA or GOSI. These are the checks we add for a Bahraini or Saudi entity, first in the test database, then again on the morning after cut-over.

Bahrain VAT

The Bahrain module (l10n_bh) installs the chart of accounts, the VAT taxes, the full and simplified tax reports and the fiscal positions, and relies on the Gulf invoice module for Arabic on invoices. Odoo 20’s only Bahrain-specific change is an update of the state codes to ISO 3166-2; the work comes from the general accounting changes, which touch every Bahraini database:

• Taxes in fiscal positions: in Odoo 20 a tax is only allowed in its own fiscal positions. If a product’s default tax does not belong to the fiscal position on the invoice, it is removed, even with no replacement. Draft one invoice per fiscal position you use (local, GCC, export, reverse charge on imported services) and compare the tax lines with production.
• Parent accounts replace account groups to structure the chart of accounts, and account codes become optional. Check the reports and exports that read the old groups.
• Bank consistency: journal entries that hit a bank account must now come from bank transactions. A team used to posting manual entries to the bank needs a new routine.
• Run the Bahrain VAT return for a closed period in the test database: it must match the return already filed with the NBR.

Bahrain had no e-invoicing mandate when we wrote our VAT and e-invoicing guide in October 2026; the invoice content rules of the NBR still apply to every PDF Odoo issues, and the upgrade should not change a single field on them.

ZATCA e-invoicing (Fatoora), phase 2

This is where Odoo 20 changes most for a Saudi company. The release notes list, among others:

• the invoice date is the official ZATCA issue date, instead of the confirmation date (Odoo has also brought this to 17.0, so an up-to-date 17, 18 or 19 database already works this way);
• ZATCA submission moves into the Send wizard, with pre-checks shown in a banner, a ZATCA tab keeping the history, and batch processing from the list view;
• the invoice type (Tax or Simplified) and the transaction type (Export, Summary or Nominal) are set on the invoice form and control the B2B or B2C routing;
• the Building Number and the Secondary Number (formerly Plot Identification) must be exactly four digits, to avoid the BR-KSA-37 rejection;
• the rounding method is fixed to document-level rounding;
• the Is Retention checkbox disappears: a negative sales tax is now treated as a retention tax;
• contacts carry an identification scheme that separates companies (TIN, CRN, MOM, MLS, 700, SAG, OTH) from individuals (NAT, GCC, IQA, PAS).

Two consequences for the test plan. First, an upgraded test database is neutralized, and the Saudi e-invoicing module’s neutralization script puts the ZATCA API mode in sandbox: test invoices go to ZATCA’s shared test environment, never to production. To test your own configuration end to end, use the Simulation (pre-production) mode on the neutralized test copy (a plain copy of a live database that has already sent invoices in production cannot leave Production mode), with a one-time password from the Fatoora simulation portal; it expires after 60 minutes, each sales journal is onboarded separately, and invoices issued there are not legally valid. Second, clean the data before cut-over: four-digit building and secondary numbers on the company, branches and B2B customers, identification schemes on contacts, retention taxes, and a ZATCA reason on every credit and debit note.

After the production upgrade, check that the API mode is still Production and that every sales journal, including the Point of Sale invoice journal, is still onboarded. Then submit the first real invoice and read the response in the chatter: accepted, accepted with warnings, or rejected. A rejected invoice is not legally valid until it is corrected and resubmitted, so a person watches the first day’s submissions. Scan a few QR codes with ZATCA’s app.

Mind the calendar too. ZATCA’s wave 25 covers taxpayers whose VAT-subject revenue exceeded SAR 187,500 in any year from 2022 to 2025, with integration due by 1 February 2027. A company in that wave should plan the upgrade and the Fatoora onboarding together, so that it tests one configuration rather than two in a few weeks.

Arabic invoices and right-to-left reports

Saudi VAT rules require tax invoices, simplified tax invoices and their credit and debit notes in Arabic; they may be bilingual. Odoo prints each document in the customer’s language, and the Gulf Cooperation Council Format option adds Arabic as a secondary language on invoices, credit notes, debit notes and vendor bills; the Bahrain module depends on the same Gulf invoice module. In Odoo 20, the Saudi invoice report gains a line-level Discount Amount column and the “Amount Due” label becomes “Invoice Total Payable Amount”.

A custom layout that inherits these reports needs the most attention: Odoo’s porting guide asks you to test your reports, and views that cause errors during the upgrade are disabled and listed in the upgrade report. Print every document type in Arabic and in English (invoice, credit note, simplified invoice, PoS receipt, delivery note, statement) and check the right-to-left alignment, the totals, the VAT number, the QR code and your Arabic translations, which Odoo’s checklist also lists.

Hijri dates

Odoo’s accounting and stock work on Gregorian dates, and its documentation describes no Hijri display. If your quotations, delivery notes or statements show the Hijri date, it comes from a custom module or report, which has to be ported and checked like any other. The ZATCA XML and the accounting periods stay Gregorian.

Payroll: Saudi localization, Bahrain custom rules

Odoo’s Saudi payroll localization (l10n_sa_hr_payroll, with l10n_sa_hr_payroll_account for the accounting entries) installs the KSA Employee salary structure, rule parameters for the Saudi and non-Saudi GOSI company contributions and the employee contribution, the employee’s nationality driving the GOSI rate, end-of-service provisions and the WPS report. Odoo 20 adds an integration with the GOSI platform to retrieve contribution portions, the GOSI Wages Update Sheet, an end-of-service computation reworked against QIWA and Ministry of Labor rules (including Article 77 terminations), an End-of-Service Benefit report, a calendar-day schedule and a “Month (30 days)” pay option.

Those are welcome changes, and they also mean the numbers can move. Run a closed month again in the test database and compare each payslip with production: net pay, GOSI lines, end-of-service provision. Check that rule parameters you edited kept their values, decide with HR which result is right wherever the new computation differs, and generate the WPS file before the real pay date.

Bahrain is not in Odoo’s list of payroll localizations, which includes Saudi Arabia, the United Arab Emirates, Oman, Jordan and Egypt. A Bahraini payroll in Odoo is built with salary rules, a GOSI (SIO) contribution logic and an LMRA WPS export, as our HR and payroll guide for Bahrain explains, so it is custom work to port and test line by line.

Multi-company and multi-currency

Many Gulf groups run a Bahraini company in dinars and a Saudi company in riyals in one database, sometimes with branches. Settings such as the ZATCA API mode are held per company: check them in each one. Odoo 20 also simplifies access rights by replacing record rules with a domain on the access right itself, so test with real users of each company, not with the administrator, and make sure nobody sees the other company’s invoices or payslips.

On currencies: scheduled actions are off in a neutralized database, so automatic exchange-rate updates do not run there; load the rates by hand before comparing reports. Odoo 20 adds the Saudi Central Bank as a rate provider, shows the rate date on converted totals, and adds a Cumulative Translation Adjustment line to the balance sheet, trial balance and general ledger, which a group consolidating BHD and SAR figures should review with its accountant. Re-run one inter-company sale and purchase if you use them.

Odoo Online, Odoo.sh or on-premise: what changes

On Odoo Online, Odoo’s team runs a silent test upgrade of each database due for one; if it succeeds in under 20 minutes, you can trigger the upgrade from the database yourself. Request a test database anyway and spend the time on the Gulf checks above: the technical part is short, the acceptance is not.

When to upgrade, and to which version

• On Odoo 17 or older: no security updates since September 2026 at the latest, a forced upgrade on Odoo Online, and the subscription surcharge for databases older than the covered versions: from March 2027 at the earliest on Odoo 17, already possible on Odoo 16 or older. Start now.
• On Odoo 18: standard support until September 2027 (planned). Plan the upgrade for the first half of 2027.
• On Odoo 19: supported until September 2028 (planned). Upgrade when an Odoo 20 feature earns it, such as the ZATCA Send wizard or the Saudi GOSI integration, or when the apps you depend on exist for 20.

From 16 or 17, the choice between 19 and 20 is practical. Odoo 20 gives the longest horizon, to September 2029; Odoo 19 has been out for a year, so third-party publishers have had more time to release compatible apps and connectors. The deciding question is usually whether everything you rely on exists for the target. Then pick a window away from a VAT return deadline, a payroll run and WPS file, a ZATCA wave deadline and the year-end close.

Common pitfalls

• Testing ZATCA only in the neutralized copy, which is in sandbox mode, and discovering a rejected invoice in production.
• Leaving a custom Arabic invoice layout untested until the first customer complains.
• Testing with the administrator account only, when Odoo 20 changed how access rights are defined.
• Skipping the upgrade report, and with it the list of views deactivated during the conversion.
• Discovering late that a third-party app has no Odoo 20 version: the whole upgrade waits for it.
• Expecting the old chatter tracking values in audit reports: Odoo 20 generates the tracking message on the fly, and a dedicated module is needed to keep tracking values.
• Cutting over in the week of a VAT return, a payroll run or a Fatoora onboarding.

Frequently asked questions

Can we go straight from Odoo 16 or 17 to Odoo 20?

Yes, with Odoo’s upgrade service and an Enterprise subscription, once your custom modules exist for 20. Check that 20.0 is offered as a target for your hosting type.

Do we need to onboard with ZATCA again after the upgrade?

Odoo’s documentation does not describe a new onboarding after an upgrade. What we check is that the API mode is still Production, that every sales journal is still onboarded, and that the first invoices are accepted. A journal you no longer use should be revoked in the Fatoora portal.

Are Studio customizations kept?

Yes, as long as Studio is installed and the subscription is active. Test them like the rest: views, reports, automations.

Is there a Bahrain payroll localization in Odoo 20?

No. Odoo’s list of payroll localizations includes Saudi Arabia and the United Arab Emirates but not Bahrain, so Bahraini salary rules and the WPS export remain custom work to carry from one version to the next.

How long does an upgrade take?

There is no standard duration. It depends on the number and size of the custom modules, the versions skipped, the apps in use, the volume of data and the time key users can give to testing. Work back from the deadline (end of standard support, or the date notified on Odoo Online) and leave room for several test cycles, a rehearsal and support after cut-over.

Working with Azinove in the Gulf

Azinove W.L.L is the group’s Gulf company, based in Isa Town, Bahrain (CR 190436-1), and an official Odoo Partner; the group has delivered more than 45 projects. For an upgrade we start with the inventory: for each module, keep, rewrite or replace with the standard. Then we run the test cycles with your key users, the Gulf checks above, the cut-over and the first weeks of support, for companies in Bahrain and in Riyadh and the rest of Saudi Arabia. Send us your current version, your hosting and your list of modules, and we will come back with what the upgrade involves; the quickest way is a 30-minute call.

Related guides: VAT and e-invoicing in Bahrain and Saudi Arabia, HR and payroll in Bahrain, trading and distribution in Saudi Arabia, contracting companies in Bahrain, and how to choose an Odoo partner, including how a partner handles the upgrade cycle.

Sources

1. Odoo — Documentation 20.0: Standard and extended support, with the support table of every version (read on 2 November 2026) — odoo.com
2. Odoo — Documentation 20.0: Upgrade: mandatory upgrades per hosting type, test and production upgrades, neutralized test databases, the test checklist, the service-level agreement — odoo.com
3. Odoo — Documentation 20.0: Upgrade a customized database: freeze, empty database, upgraded database, upgrade scripts, rehearsal — odoo.com
4. Odoo — Odoo Enterprise Subscription Agreement, version 13 (24 September 2026): covered versions, upgrade services, working with an Odoo Partner, fees for non-covered versions — odoo.com
5. Odoo — Odoo Upgrade Service, upgrade request form (read on 2 November 2026) — upgrade.odoo.com
6. Odoo — Documentation 20.0: Odoo Online, incompatibility with custom modules and Odoo Apps Store modules — odoo.com
7. Odoo — Odoo 20 Release Notes (September 2026): accounting, Saudi Arabia, United Arab Emirates and Bahrain localizations, technical changes — odoo.com
8. Odoo — Documentation 20.0: Saudi Arabia fiscal localization: modules, company fields, invoicing language, ZATCA sandbox, simulation and production modes, API responses — odoo.com
9. Odoo — Documentation 20.0: Saudi Arabia payroll localization: modules, GOSI rule parameters, end of service, WPS report — odoo.com
10. Odoo — Documentation 20.0: Payroll, with the list of payroll localizations — odoo.com
11. Odoo — Documentation 20.0: Multi-company: shared and company-specific settings, user access, inter-company transactions — odoo.com
12. Odoo — Documentation 20.0: Multi-currency system: main currency, automatic currency rates, exchange difference entries — odoo.com
13. Odoo — Source code 20.0: Saudi Arabia – E-invoicing module (l10n_sa_edi), including the neutralization script that puts the ZATCA API mode in sandbox, LGPL-3 — github.com
14. Odoo — Source code 20.0: Bahrain – Accounting module (l10n_bh), LGPL-3 — github.com
15. Odoo — Source code 20.0: Gulf Cooperation Council – Invoice module (l10n_gcc_invoice), Arabic as a secondary language on invoices, LGPL-3 — github.com
16. ZATCA — E-invoicing: introduction, phase 1 (generation) and phase 2 (integration) (read on 2 November 2026) — zatca.gov.sa
17. ZATCA — Wave 25 of the integration phase, criteria and deadline (24 July 2026) — zatca.gov.sa
18. National Bureau for Revenue (Bahrain) — VAT: law, regulations and guides — nbr.gov.bh