OpenCart 3 to OpenCart 4 Upgrade: What Breaks and How to Plan It

If you run an OpenCart 3 store, you've probably wondered whether it's time to move to OpenCart 4. Maybe your host is pushing you onto a newer PHP version. Maybe an extension developer has stopped updating their OC3 module. Or maybe you just want to be on the current platform.

The catch is that OpenCart 4 is not a simple version bump. It's a substantial rewrite, and most of what makes a real store work (extensions, the theme, the payment gateway, your SEO URLs) changes underneath you.

We run large OpenCart stores on both versions. This guide covers what actually changes, what tends to break, and how we'd plan the move.

First question: do you need to move yet?

OpenCart 3 is still maintained. Version 3.0.5.0 added PHP 8.4 compatibility, and 3.0.5.1 (released August 2026, the same day as 4.1.0.4) added PHP 8.5 support.

So if the only reason you're looking at OpenCart 4 is "my host wants me on PHP 8", updating to the latest 3.0.5.x may solve that with far less risk. Plenty of experienced voices on the OpenCart forum still recommend exactly that.

Moving to OpenCart 4 makes sense when you're already planning a redesign, your extensions need replacing anyway, or you want the newer admin, Bootstrap 5 front end and built-in features like the blog and CMS pages. Make that decision deliberately, not because of a hosting email.

What's current

At the time of writing, the latest release is OpenCart 4.1.0.4. Its installer requires PHP 8.1 or newer, and it includes fixes for PHP 8.5. Some official docs still say PHP 8.0+, but the 4.1.0.4 installer checks for 8.1, so plan for at least that.

Is there an official upgrade script?

Yes, sort of. OpenCart 4 ships an upgrade wizard in the /install folder, and the official docs describe the process: back up, upload the new files except your config files, image and system/storage folders, then browse to /install and run the upgrade.

Two things are worth knowing before you rely on it:

• The 4.1.0.4 upgrade notes only cover upgrades from 4.1.0.0 to 4.1.0.3. They say not to use them with earlier versions, and suggest contacting OpenCart's paid support if you're coming from something older.
• Community experience is poor for 3.x stores. Forum threads report upgrades that ran but left every extension missing from the admin, and long-standing members say the built-in upgrade "will almost always fail", especially on stores using a theme framework like Journal.

Our view is simple: treat OpenCart 4 as a migration, not an upgrade. Build a fresh OpenCart 4 install alongside your live store, move the data across, rebuild what needs rebuilding, test, then switch over.

What breaks

Extensions

This is the big one. OpenCart 3 extensions do not run on OpenCart 4. In 4.x, extensions live in their own folder (extension/vendor-name/...), use PHP namespaces and are packaged as .ocmod.zip files with an install.json. An OC3 module needs a proper 4.x version, not a tweak.

OCMOD has had a bumpy ride:

• 4.0.0.0 removed OCMOD entirely, leaving the event system as the only way to modify behaviour.
• 4.1.0.0 added it back, and 4.1.0.4 includes further OCMOD fixes.

Even where OCMOD exists, your old XML modifications point at OC3 file paths that no longer exist, so they need rewriting. The official guidance is to prefer events where possible.

Events changed within 4.x too. In 4.0.2.x the action syntax moved from class|method to class.method, which broke extensions written for 4.0.1.x. If a developer tells you their module is "OpenCart 4 compatible", ask which 4.x versions they've actually tested.

Theme

OpenCart 3 ships Bootstrap 3. OpenCart 4 uses Bootstrap 5 (5.3.8 in 4.1.0.4). Both now bundle Twig 3, so the template engine isn't the problem. The markup, template structure and CSS framework are, though. A custom OC3 theme will need rebuilding, not copying over.

Payments

This catches people out. OpenCart 3.0.5.1 bundles 48 payment extensions in core, including PayPal, Opayo, Worldpay, Square and Klarna. OpenCart 4.1.0.4 bundles four: bank transfer, cheque, cash on delivery and free checkout.

Whatever card gateway you use today, you'll need a separate OpenCart 4 extension for it, tested end to end on your staging store before launch.

Database

The schema changes in places that matter. A good example is the SEO URL table. In OpenCart 3, oc_seo_url stores a query such as product_id=42. In OpenCart 4 it stores a separate key and value, plus a sort_order. Recurring profiles were also reworked into subscriptions, and internal routes changed from | to . separators.

That's why copying tables across with phpMyAdmin rarely works cleanly. Data has to be mapped, not just copied.

SEO URLs

If your product and category URLs change, you lose rankings. OpenCart 4 also adds default keywords for routes like brand and blog, which may differ from what an OC3 extension gave you.

The fix is old-fashioned and reliable: crawl every URL on the live store before you start, compare it against the new store, and set up 301 redirects for anything that differs. We cover the wider process in our guide to website migration planning.

A practical migration checklist

1. Decide why you're moving. If PHP support is the only reason, consider updating to the latest 3.0.5.x instead.
2. Audit every extension. List each one, what it does and whether a tested OpenCart 4.1.x version exists. Mark each as replace, rebuild or drop.
3. Check your theme. Assume a custom or framework theme needs rebuilding for Bootstrap 5.
4. Confirm your payment gateway has an OpenCart 4 extension and plan a full test transaction.
5. Check hosting. PHP 8.1 or newer, and ideally the same PHP version on staging and live.
6. Back up everything. The database and files, and keep a copy you never touch.
7. Crawl the live store. Export every product, category, information and manufacturer URL.
8. Build a fresh OpenCart 4 install on staging. Don't overwrite your OC3 files.
9. Migrate the data. Products, options, categories, customers, orders and SEO keywords, mapped to the new schema, then spot-check by hand.
10. Rebuild custom functionality with events first, OCMOD only where needed.
11. Test the whole journey. Browse, search, add to basket, checkout, payment, order emails, admin order handling and any integrations.
12. Set up 301 redirects for every URL that changed.
13. Plan the switchover for a quiet trading period, with a freeze on new orders in the old admin while you do the final data sync.
14. Monitor after launch. Watch error logs, Search Console and conversion rate for the first few weeks.

Frequently asked questions

Can I upgrade OpenCart 3 to 4 with the built-in upgrade script?

You can try, on a copy. The official upgrade notes for 4.1.0.4 only cover 4.1.0.x stores, and community reports for 3.x stores are mostly negative. A fresh install with a planned data migration is the safer route.

Will my OpenCart 3 extensions work on OpenCart 4?

No. OpenCart 4 uses a different extension structure, namespaces and packaging. You need a 4.x version of each extension, or a replacement.

Does OpenCart 4 support OCMOD?

It does again. OCMOD was removed in 4.0.0.0 and added back in 4.1.0.0. Old OC3 OCMOD files still need rewriting because the file paths have changed.

What PHP version does OpenCart 4 need?

The 4.1.0.4 installer requires PHP 8.1 or newer.

Will I lose my Google rankings?

Not if you plan for it. Keep URLs the same where you can, and 301 redirect anything that changes. Then watch Search Console closely after launch.

Should I just stay on OpenCart 3?

For many stores, for now, yes. OpenCart 3.0.5.x is maintained and supports current PHP versions. Move to 4 when it fits a wider plan, not under pressure.

Need a hand?

An OpenCart 3 to 4 move is really a rebuild with your data carried across. Done carefully, you end up with a cleaner, faster store. Rushed, you lose orders and rankings.

If you'd like help working out whether to stay or move, have a look at our OpenCart development and legacy modernisation services, or see the kind of large catalogue store we work on in our Balliihoo case study. When you're ready, get in touch, we're happy to look at your store and give you an honest answer.