Upgrade guide

How to Upgrade Zen Cart 1.5.x to 2.2.2 Safely

📅 Updated May 2025

⏱ 15 min read

🛒 From any 1.5.x release

Before you start — honest assessment

A 1.5.x → 2.2.2 upgrade is not a one-click process. Zen Cart 2.0 introduced significant structural changes that break most custom templates and many third-party modules.

If your store has a custom theme or more than 3–4 custom plugins, budget at least 8–15 hours of work. If you've never done a Zen Cart upgrade before, consider getting professional help — a botched upgrade that corrupts your product database will take far longer to recover than a clean professional upgrade would have cost.

What's in this guide

What changed in Zen Cart 2.0 / 2.2.2
What will break on your store
Before you start — full backup procedure
The upgrade process step by step
After the upgrade — what to check
Should you do it yourself or hire help?

What changed in Zen Cart 2.0 / 2.2.2

Zen Cart 2.0 (released May 2024) and 2.2.2 are major releases — the most significant since the 1.3→1.5 transition. The key changes that affect store owners:

PHP 8.x support: 2.2.2 is fully compatible with PHP 8.3. Your 1.5.x store is probably struggling with PHP 8.0+ already.
Bootstrap 4 → 5: The default template now uses Bootstrap 5. If your theme uses Bootstrap 4 classes, you'll need to update it.
Rewritten template system: Template overrides work differently in 2.x. Custom templates need to be refactored, not just copied over.
Updated payment modules: The PayPal Classic API module is replaced with the PayPal Commerce Platform module.
MySQL 8.0+ compatibility: Database queries have been updated to work with current MySQL/MariaDB versions.
New admin UI: The admin panel has been significantly redesigned. Layouts and menu locations have changed.

What will break on your store

Here's an honest compatibility assessment for common store components:

Component	Compatibility with 2.2.2	What to do
Your product data, orders, customers	✓ Preserved	Database migration handles this automatically
Custom template / theme	✗ Will break	Needs to be rebuilt or migrated to Bootstrap 5
Core Zen Cart plugins (from zen-cart.com)	~ Check each one	Many have been updated — check downloads for 2.x versions
Custom-built modules	✗ Needs porting	Requires developer to review and update code
PayPal Standard / Classic	✗ Deprecated	Switch to PayPal Commerce Platform module
Stripe, Square, Authorize.net modules	~ Check version	Install the 2.x-compatible version from their repositories
UPS / USPS / FedEx shipping modules	~ Check version	Updated versions available — APIs have also changed
Google Analytics integration	✗ Needs update	Old UA integration doesn't work — need GA4 module

Before you start — full backup procedure

Do not skip this section. Every upgrade goes wrong occasionally. A proper backup means "wrong" becomes a 30-minute restore, not a week of panic.

⚠ Non-negotiable

Take a full backup immediately before starting the upgrade. Not last night's automated backup — a fresh one right now, before you touch anything.

Backup step 1

Back up your database

This contains all your products, orders, customers, and configuration. It's the most critical thing to preserve.

Log into your hosting control panel → phpMyAdmin
Select your Zen Cart database from the left panel
Click Export → Format: SQL → Go
Save the .sql file to your local computer and also to a cloud storage location

Alternatively, via SSH: mysqldump -u username -p database_name > backup_$(date +%Y%m%d).sql

Backup step 2

Back up all store files

Download a complete copy of your store's file system via FTP. Pay special attention to:

/includes/configure.php — your database credentials and site URLs
/admin/includes/configure.php — admin configuration
/includes/templates/ — your custom theme
/includes/modules/ — custom modules
/images/ — product images

✓ Backup verification

Before proceeding: open your .sql backup in a text editor and confirm you can see your product names and order data. An empty or corrupt backup is not a backup.

The upgrade process step by step

Phase 1

Set up a staging environment

Never upgrade directly on your live store. Create a staging copy first — most hosts offer one-click staging in their control panel, or you can create a subdomain like staging.yourstore.com.

Copy all your store files to the staging location
Export and import your database to a new staging database
Update configure.php on staging with the new database credentials and staging URL
Verify the staging site works correctly — it should look and behave identical to your live store

Phase 2

Inventory your customisations

Before installing the new Zen Cart version, document everything custom about your store:

List all active plugins/modules and their versions
Note which template you're using (default, custom, third-party)
List any files you've modified in /includes/ or /admin/
Screenshot your admin configuration pages (shipping, payment, email settings)

This list becomes your post-upgrade checklist.

Phase 3

Install Zen Cart 2.2.2 on staging

Download Zen Cart 2.2.2 from zen-cart.com
Upload the new files to your staging server, overwriting the existing ones (do not delete — just overwrite)
Run the Zen Cart upgrade script by visiting: https://staging.yourstore.com/zc_install/
Follow the installer — it will update your database schema to 2.2.2
Delete the /zc_install/ folder after completion

Phase 4

Fix what broke

This is where most of the work happens. Working through your customisation inventory from Phase 2:

Template: Switch to the default 2.2.2 template first. Confirm the store works. Then gradually re-apply your customisations.
Plugins: Check each plugin on the Zen Cart downloads page for a 2.x-compatible version. Install the updated versions.
Custom modules: These need code review. PHP 8.x removed several deprecated functions that older Zen Cart modules commonly used (especially mysql_* functions and old-style constructors).
Payment gateways: Install fresh copies from the payment provider's current Zen Cart module, not your old module files.

Phase 5

Test everything on staging

Before touching your live store, complete this test checklist on staging:

Browse categories and product pages — check images load, prices display correctly
Add items to cart, proceed through checkout
Complete a test payment using sandbox/test credentials for each payment gateway
Check that order confirmation emails send and arrive
Log into admin and verify orders appear correctly
Test on a mobile device — confirm layout is responsive
Run a Google PageSpeed test and compare with your pre-upgrade score

Phase 6

Go live

Once staging is working correctly:

Schedule the go-live during your lowest-traffic period (typically 2–4 AM local time)
Put your live store into maintenance mode first
Apply the same changes to your live server that worked on staging
Run the upgrade installer on live
Repeat the test checklist above on the live store before removing maintenance mode
Monitor closely for the first 24 hours

After the upgrade — what to check

Resubmit your sitemap to Google Search Console — URL structures may have changed
Check that your robots.txt still correctly blocks the admin directory
Verify SSL is still valid and HTTPS is enforced sitewide
Test IPN: place a real low-value order and verify it registers in Zen Cart
Check page load speed — 2.2.2 should be faster, but verify with a real test
Review your admin security settings — confirm the admin path is still obfuscated

Should you do it yourself or hire help?

Do it yourself if:

You're running the default Zen Cart template (no custom theme)
You have only 1–2 plugins, both of which have published 2.x-compatible versions
You're comfortable with FTP, phpMyAdmin, and reading PHP error messages
You have a few days available to work through issues that come up

Consider getting professional help if:

You have a custom or heavily-modified theme
You have custom-built modules that need code review
Your store can't afford to be down for more than an hour
You're upgrading from 1.3.x — this is a more complex migration than 1.5.x → 2.2.2
You've tried the upgrade and something has broken that you can't diagnose

Want us to handle the upgrade?

We've done this 300+ times. We work on staging, port your custom modules, and go live when everything is confirmed working.

Upgrades from 1.5.x start at $299 — fixed price, not hourly.

Get an upgrade quote