OpenCart 4 Upgrade Guide: How to Move from OpenCart 3 Without Breaking Your Store

If you are planning an OpenCart 4 upgrade from OpenCart 3, the short version is this: treat it as a migration, not an update. The core database tables are similar enough to carry your products, customers and orders across, but almost every extension, theme and modification you rely on was written for 3.x and will not load on 4.x. The stores I see go wrong are the ones that uploaded the new files over the old ones and hoped. The ones that go right build OpenCart 4 fresh on a staging copy, move the data in, replace each extension deliberately and test checkout end to end before switching DNS.

This guide is the process I follow, in the order I follow it.

Why an OpenCart 4 upgrade is really a migration

OpenCart 4.0 was a large rewrite rather than an incremental release. The parts that matter for an upgrade:

• Extensions moved and gained namespaces. In 3.x an extension scattered files across admin/, catalog/ and system/. In 4.x each extension lives in its own folder under extension/<name>/ with its own admin and catalog sub-folders, and classes are namespaced (for example Opencart\Catalog\Controller\...). A 3.x extension is not a drop-in; it has to be rewritten or replaced with a 4.x version.
• OCMOD changed. OCMOD was removed in the early 4.0 releases and later returned in a more limited form. Many developers moved to the event system instead. Any 3.x store that depends on a stack of OCMOD XML modifications to core files needs every one of those reviewed, because the files they patched have changed or moved.
• Themes need rebuilding. OpenCart 4 still uses Twig, but the default templates, the Bootstrap version and the layout structure changed. A 3.x theme usually has to be rebuilt or swapped for a 4.x theme.
• PHP requirements rose. OpenCart 4 needs PHP 8. Many 3.x stores run on PHP 7.x hosting, so the server often needs attention too. The exact minimum has moved between 4.x point releases, so check the install notes for the release you choose.

So the honest question is not “how do I upgrade opencart 3 to 4” but “how do I rebuild my store on OpenCart 4 and bring my data with me”. Framing it that way sets the right budget and timeline from the start.

Step 1: Audit the current store

Before touching anything, write down what the store actually does. I build a spreadsheet with one row per item:

• Every installed extension — payment, shipping, modules, feeds, order totals, analytics. Note the vendor and whether a 4.x version exists.
• Every OCMOD and vQmod modification under Extensions > Modifications, plus anything in system/storage/modification/. Each one is a behavior you will lose unless you replace it.
• Core file edits made directly by previous developers. A diff against a clean copy of your exact 3.x version finds them.
• Integrations — ERP, accounting, marketplace feeds, stock sync. These often read or write the database directly and will break silently if table structures change.
• Traffic-earning URLs — export the top landing pages from Search Console so you know which URLs must keep working.

# find core edits: compare live files against a clean 3.0.3.x download
diff -rq --exclude=image --exclude=storage --exclude=config.php \
  ./opencart-3.0.3.9-clean/upload/ /var/www/store/

For each extension you have three options: buy the vendor’s 4.x version, find an equivalent, or drop it. Stores accumulate extensions they no longer need, and an upgrade is the cheapest time to remove them.

Step 2: Build OpenCart 4 on a staging copy

Never do this on the live store. I set up a staging subdomain on the same kind of hosting that production will use, with PHP 8 and the database version you plan to run.

1. Take a full backup of the live 3.x files and a mysqldump of the database, and confirm the dump restores.
2. Install a clean copy of the current stable OpenCart 4 release on staging with an empty database.
3. Rename the admin folder and move storage/ outside the web root when the installer prompts you. It is easier now than later.
4. Install the 4.x theme and each replacement extension through Extensions > Installer, which takes .ocmod.zip packages.

mysqldump --single-transaction --routines --default-character-set=utf8mb4 \
  -u store_user -p store_db > oc3-$(date +%F).sql

Keep the live store running and taking orders the whole time. Staging is where every mistake should happen.

Step 3: Migrate products, customers and orders

This is the part people expect to be hard, and it is mostly mechanical. Products, categories, manufacturers, options, attributes, customers, addresses, orders and reviews live in tables with largely the same names in 3.x and 4.x, but columns have been added, renamed and removed. My approach is a script that maps old tables to new ones explicitly, rather than importing the old dump over the new schema:

• Load the 3.x dump into a separate database on staging (oc3_source).
• For each table, INSERT INTO oc4.table (columns...) SELECT columns... FROM oc3_source.table, handling new NOT NULL columns with sensible defaults.
• Copy image/catalog/ across so product image paths still resolve.
• Check row counts table by table, then spot-check twenty products, ten customers and ten historical orders in the admin.

Two things to verify specifically. First, customer passwords: log in on staging as a test customer created on the old store, with the old password, and confirm it works. If it does not, plan a password-reset email rather than discovering it on launch day. Second, order statuses and totals: historic orders should display the same totals, tax lines and status history as they did in 3.x, because your accounting depends on them.

Write the script so it can be rerun. You will run it once for a trial and again at cutover with fresh data.

Step 4: Replace extensions and modifications

Go down the audit spreadsheet row by row. For each OpenCart 4 extension, install it on staging, configure it with the same settings as live, and note anything that behaves differently. Payment extensions deserve the most attention: use the gateway’s sandbox credentials on staging, and confirm the 4.x module supports the same features you use today, such as saved cards, refunds from the admin or 3-D Secure.

For custom modifications there is no shortcut. A behavior that used to be an OCMOD patch on a core controller should become an event handler in a small custom extension. That keeps it separate from core, so the next 4.x point release does not overwrite it. This is where most of the development time in an OpenCart 4 upgrade goes, and it is the work my OpenCart development service usually covers.

Step 5: Preserve SEO URLs and set up redirects

Losing rankings is the most expensive mistake in an OpenCart 3 to 4 migration, and it is avoidable. In 3.x the seo_url table stored a query such as product_id=42 against a keyword. In 4.x the table stores the key and value in separate columns, so the migration script has to split them rather than copy the row as is.

INSERT INTO oc4.oc_seo_url (store_id, language_id, `key`, `value`, keyword)
SELECT store_id, language_id,
       SUBSTRING_INDEX(query, '=', 1),
       SUBSTRING_INDEX(query, '=', -1),
       keyword
FROM oc3_source.oc_seo_url
WHERE query LIKE '%=%';

Then compare the URL structure. Depending on the 4.x version and settings, product and category URLs may include a language segment or a different path format from your 3.x URLs. Take your exported list of top landing pages and request every one on staging. Anything that does not return a 200 at the same path needs a 301 redirect in the web server config, not a redirect extension that runs after OpenCart has booted.

# nginx: permanent redirect for an old 3.x path
location = /laptop-notebook { return 301 /laptops; }
location = /apple-cinema-30 { return 301 /laptops/apple-cinema-30; }

Also check canonical tags, the XML sitemap and robots.txt on staging, and make sure staging itself is blocked from indexing so Google does not find a duplicate store.

Step 6: Test checkout, payments and emails

The store is not ready until a real order has gone through every path customers use. My test list:

• Guest checkout and registered checkout, with and without a coupon.
• Every shipping method, including free-shipping thresholds and zone-based rates.
• Every payment method in sandbox mode, including a declined card and a 3-D Secure challenge.
• Tax calculation for each tax class and customer group you sell to.
• Order confirmation, admin notification and status-change emails, checked in an actual inbox for layout and deliverability.
• Stock decreasing on order, and any external sync (ERP, feed, marketplace) picking up the new order.
• Refund or cancel an order from the admin to confirm the gateway call works.

Check the PHP error log after each test. OpenCart 4 on PHP 8 is stricter, and warnings that were silent on 3.x often point at an extension that is only half working.

Step 7: Cut over with a way back

Pick a low-traffic window. Put the 3.x store into maintenance mode, run the migration script one last time so orders and customers from the last few days come across, run a short smoke test, then point DNS or the web server at the new install. Keep the old store and database untouched for at least a couple of weeks. If something serious turns up, you can switch back while you fix it. After launch, watch Search Console for crawl errors and 404s daily for the first two weeks. The same cutover discipline applies to any platform move, which I cover in more detail in how to migrate a website without downtime.

When it is worth getting help

If your store runs few extensions and no custom code, a careful owner can follow the steps above. Once there are custom modifications, a payment gateway with no 4.x module, or years of SEO traffic riding on the URLs, it is usually cheaper to have it done once properly. I handle OpenCart 3 to 4 upgrades as a fixed-price project agreed in writing after the audit, with smaller fixes at $20/hour. If that sounds useful, have a look at my OpenCart upgrade and development work, or see server migration if the move also involves new hosting.

Frequently asked questions