Welcome to Zen Cart™ ...


The Zen Cart™ software is made available to you for use, additions, changes, modifications, etc. without charge, under the GNU General Public License.

While we do not charge for this software, donations are greatly appreciated each time you download a new version, to help cover the expenses of maintenance, upgrades, updates, the free support forum and the continued development of this software for your online e-commerce store.

Donations can be made at: The Zen Cart™ Team Page

We appreciate your support.
The Zen Cart™ Team

Zen Cart™ is derived from: Copyright 2003 osCommerce
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
and is redistributable under the GNU General Public License


This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.

3 EASY STEPS TO UPGRADE ZEN CART™

Paypal IPN - Important:
If upgrading from versions prior to 1.2.2d

This version of Zen-Cart contains a new implementation of the Paypal IPN payment module. If you are already using Paypal IPN please be sure to read the following paragraph.

The Paypal IPN code has been re-written for a couple of reasons. Firstly, previous converted oSC contributions did not work correctly with Gift Vouchers & Discount Coupons. This also means that any future Order Total methods similar to GV's and discount coupons would have problems working with Paypal IPN. Secondly, because of the original layout of checkout code, the Paypal IPN code was unecessarily complicated. We have re-written large portions of checkout code in order to greatly reduce the complexity of Paypal IPN code.

If you are already using Paypal IPN you should be aware of the following consquences:
  • The new Paypal IPN code does not support the following:
    • Customised Paypal Page Layouts
    • Also changes to paypal database table structure/contents from previous versions
  • You should also be aware of the following
    • You should ensure you make a hard copy of the detail contained in the old admin Paypal IPN list prior to upgrading
    • You will lose your old IPN history details due to database changes for this new support
    • See special upgrade instructions regarding "Activating PayPal" at the end of this document

We will be actively upgrading IPN for future versions based on user feedback.

Getting Started ...

This is a basic guide to upgrading Zen Cart™. If you have not yet installed Zen Cart, please see the 1.Readme-INSTALLATION.html file for installation instructions.

To upgrade Zen Cart™, you'll need the same basic tools you used to install and customize it in the first place: An FTP program, a text editor friendly to HTML/PHP code, phpMyAdmin or equivalent access to your MySQL database, and your Control Panel for managing your webspace.

Additionally, you will find a file-comparison tool like WinMerge to be very helpful.

Upgrading follows 3 easy steps. We suggest you take your time going through each stage carefully and methodically. Don't rush the process. And as always, be sure you keep good backups first.

We highly recommend you pay special attention to getting familiar with the demo data in the new version, so that you can become comfortable with the many new features contained in the new release.

1. Preparation

Unzip a copy of the new version of Zen Cart™, upload it to your webserver into a "demo" folder, and install the new version into a separate database, and include the Demo products. This is just for a place for you to play with the new version and get used to its new features. These can be deleted after conversion is complete.

Study the new features, and the documented changes to the template structures, as well as the "changelog". Use the demo products in the demo shop as examples. See also the supporting documentation provided with the new release.


Make a full backup of your database (dump to SQL file). Store this file on your PC for later reference.

Make a full backup of your site files (ftp to your PC and zip it up for safe-keeping).
Keep the backup on your PC to use in next steps. Perhaps call this folder "\zen_backup".


Now let's find out the differences/customizations details between your site and the original Zen Cart files.

Unzip a copy of the original Zen Cart™ files for the version you originally installed or last upgraded from (ie: perhaps v1.1.3 or even 1.2.0). This should be placed in a separate working folder on your PC (perhaps "\zen_orig").

Make a list of any add-ons you have installed, for later reference.

Run a tool like WinMerge to compare the "Original" Zen Cart™ files in "\zen_orig" against your working backup files in "\zen_backup".
Note all the files that are "different". In WinMerge, double-click on each file and note what the differences are.
If the differences are just language defines for display text, those will be simple to carry forward.
If the differences are actual programming/code differences, you will need to make detailed notes in order to carry over those changes to the new new new version.
Any mods/add-ons you've installed will likely contain many programming changes, and may not be fully compatible with the newer Zen Cart™ release.

Your list of add-on's may help you narrow down the source of any differences you're finding between versions. You may have to download the add-on again to take a look at the readme or code contained in it. You may have to contact the author to ask for an updated version.


As you make your list of changed files, etc, at this stage, you may want to move things into the Zen Cart™ template-override structure, if you haven't already done so. See the Zen Cart™ site for FAQ's on the template system.

2. Execution

Download and unzip the latest Zen Cart™ version to your PC. This will be in a 3rd directory (perhaps "\zen_new"), separate from the other two folders compared above.

Using the list of files you made earlier, go through each "changed" file, and make your changes from the old version into the new version.
Simple language edits will be just a matter of copy-and-paste.
Programming changes to core components will be more difficult and require significant testing.
You may find WinMerge handy at this stage to apply edits as well. However, you will see many extra differences that may not be related to your own customizations, or that may conflict. Be careful making changes to program code.

Note that there will be several changes you will have to make to files that you have overridden using the template overrides system. Thus, you'll want to compare files from /includes/templates/MYTEMPLATE/* to /includes/template/template_default/* ... and the same with language file overrides, sideboxes, etc.

3. Testing

Make a NEW database to install the new version of Zen Cart™ into.

If the last backup you made of your data is older than the last order that might have been processed or customer registration, make a fresh database backup.
Restore your database from the backup in step #1 earlier into your NEW database just created.

If your /zen_new folder doesn't have "/includes/configure.php" and "/admin/includes/configure.php" files, copy them from your old store folder.

EDIT your "/zen_new/includes/configure.php" file and ensure that your DATABASE_NAME matches your NEW database. Also verify database username and password in case that information has changed. Save this file, and be sure to upload it as part of the next step:

Upload the files from your modified "new version" (created in step 2) to your server, into an alternate folder, perhaps called "/store_new".

Run /zc_install/index.php and choose "Upgrade" when prompted. (Don't select "Install", or you will overwrite your database.) (If "Upgrade" is not offered, then the installer was unable to connect to your database to confirm what version its structure is at. Check your configure.php settings.)

Test your customizations. Edit as needed. Compare with the test/demo install performed earlier, as needed.

When satisfied that all is OK, go live.
If significant time has passed since you did your last backup, you may want to repeat the steps in this "Testing" section again, using a fresh backup from your live shop. You don't need to re-upload files again ... simply do the database restore, and run the installer to do the database upgrade again.

To go live, put your shop into "Down for Maintenance" mode in the admin area. Be sure to add your IP address to the list of allowed addresses to get into the site for previewing.
This can be done easiest by renaming "store_new" to "store". (You'll have to rename "store" to something else first.)
Test it to be sure that things are operating as desired. If you have small problems to repair, turn "Down for maintenance" on and off again as necessary.

Help and Support

For additional help and support issues, check out our FAQ's and visit our Support Forums on the web at: www.zen-cart.com

Good Luck with your upgrade. We're glad you're enjoying the Zen Cart™ Experience!


Special Upgrade Steps Specific to Zen Cart™ Versions

Upgrading from v1.2.1, v1.2.2 or v1.2.3

Upgrade is a simple process:
  • Ensure that you merge your customizations into the new distribution files from the Zen Cart™ v.1.2.5 zip file. Refer to the changelog for more detailed information on changes.
  • Then upload the new version files, including the files for your customizations/templates, to your webserver.
  • Run the Installer (zc_install/index.php) to upgrade the database structure. On the "System Inspection" page, you'll be offered the option to "Install", "Upgrade", or "Upgrade Database Only". If you're upgrading from v1.2.1, v1.2.2, v1.2.3 or v1.2.4, you may choose "Upgrade Database Only", as you won't need to change the contents of the configure.php files.

Files which can be deleted

The following files can be safely deleted from your system:
/ipn.php
/admin/paypal_ipn.php
/admin/paypal_ipn_order.php
/admin/includes/classes/paypal_ipn.class.php
/admin/includes/languages/english/paypal_ipn.php
/admin/includes/languages/english/images/buttons/button_products_price_manag.gif
/includes/classes/paypal/*.* (whole folder)
/includes/languages/english/bb_index.php
/includes/modules/pages/bb_modules/*.* (whole folder)
/includes/modules/payment/paypal/application_bottom.inc.php
/includes/modules/payment/paypal/application_top.inc.php
/includes/modules/payment/paypal/admin (whole folder)
/includes/modules/payment/paypal/catalog (whole folder)
/includes/modules/payment/paypal/classes (whole folder)
/includes/modules/payment/paypal/functions (whole folder)
/includes/modules/payment/paypal/images (whole folder)
/includes/modules/payment/paypal/languages (whole folder)
/includes/templates/template_default/templates/tpl_bb_modules_default.php


Activating the PayPal Payment Module

In each of 1.2.1, 1.2.2, and 1.2.3, the PayPal module had overhauls. If you are using the PayPal module, you'll need to reactivate it after installing the new files:
To activate it, you'll need to "Remove" and "Install" the PayPal module in Admin | Modules | Payment. Take note of the email addresses already configured in your PayPal module before removing, so you can re-enter them after Installing the module again.


Zen Cart™ Copyright 2005