Data Migration Process
page last edited on 21 May 2019
Once the X-Cart v4 to v5 Data Migration Wizard addon has been installed, you will see a new ‘Migration wizard’ section at the top of the X-Cart 5 Admin area menu:
If you are not able to install X-Cart v4 to v5 Data Migration Wizard module from the marketplace and see the following warning message:
Please make sure to install Order import module first and then try to install X-Cart v4 to v5 Data Migration Wizard module again.
Click it to launch the migration process.
Table of Contents
- Step 1 - Start
- Step 2 - Connect
- Step 3 - Check
- Step 4 - Select
- Step 5 - Enable
- Step 6 - Transfer
- Step 7 - Complete
Step 1 - Start
In the first step of the wizard, select the checkbox to confirm that you understand the consequences of using the wizard. Namely, all the existing data in your X-Cart 5 store will be overwritten.
Click Start migration to proceed:
Step 2 - Connect
In the second step of the wizard, specify your X-Cart 4 store MySQL connection details.
Start by completing the following fields:
- Database name: The name of your X-Cart 4 database.
- Database username: The username of its MySQL account.
- Database password: The password of its MySQL account.
If this set of fields is not enough to set up a proper connection, use the Advanced options section (expands by the click of the respective button):
In the Advanced options section, you can enter the following info:
- Host name - the name of the host where your MySQL server is running;
- Port number - the port number to use for the connection, for connections made using TCP/IP. The default port number is 3306;
- Socket - Unix’ MySQL socket;
- Table prefix - the table prefix used in your X-Cart 4 database (as was specified during X‑Cart 4 installation). If you do not remember the table prefix that was used for your X-Cart 4 tables, you can look it up in the file
init.phpof your X-Cart 4 installation (in X-Cart versions 4.5.3 and later, see the value of
XC_TBL_PREFIX; in earlier versions - the value of
xcart_tbl_prefix). The default table prefix for all X-Cart 4 versions is
After specifying the above details, define the following settings:
- Encryption key - your X-Cart 4 store’s Blowfish key (the secret key needed to access certain types of data stored in encrypted form, such as user passwords). More info about Blowfish key.
- Site URL - the URL of your X-Cart 4 store;
- Site path - this option represents where X-Cart 4 store is located on the server. Use it only when you have X-Cart 5 and X-Cart 4 on the same server.
Click Save and continue.
Step 3 - Check
In the third step of the wizard, your X-Cart 5 store tries to connect to the specified X-Cart 4 database using the connection details provided earlier.
If connection details are specified correctly, you will see a summary of information that is going to be migrated from X-Cart 4 to X-Cart 5:
The “Images size” item shows the amount of space taken by the X-Cart 4 store images in MB. If you are going to migrate the images, make sure that you have enough disk space on your X-Cart 5 hosting.
Click Continue to proceed.
Step 4 - Select
In the fourth step of the wizard, you will see a list of data types that can be migrated from your X-Cart 4 store to X-Cart 5.
Select the data types that need to be migrated to X-Cart 5, then click Save and continue:
If you want to try to do the migration in demo mode this time, select the Demo migration option at the top of the page:
Click Save and continue.
Step 5 - Enable
In the fifth step, the wizard will provide you with a list of X-Cart 5 addons that have to be enabled in order to match X-Cart 4 functionality:
Click Enable and continue.
What happens next depends on whether your X-Cart 5 store is a trial installation or using some kind of license (free or non-free).
Trial installation (NO license is activated)
On a trial installation, the process will activate all the required addons:
If any paid addons are installed at this step, you will get a warning that licenses must be purchased:
In this case, you can either activate an addon license or remove it from your store.
You may choose to resolve the licensing problem right away, or you may close the popup window with the warning and continue with the migration process. However, please be aware that the license warning will continue to appear in your X-Cart 5 store (at both the back-end and the storefront) until you purchase the license or remove the addons.
On our demo, we used a trial installation, so we got the first type of warning and chose to activate a license key for X-Cart Ultimate. After activating the key, we got a message at the top of the screen showing that the key has been activated successfully:
This means that our licensing problem has been resolved, and we can go back to our migration process:
On a licensed installation, the scenario of the wizard “Step 5 - Enable” will be a bit different after the Enable and continue button is clicked.
If the wizard detects that addons cannot be used with your type of X-Cart license, after these addons are downloaded, you will get a license warning as follows:
In this case, you can resolve the problem either by upgrading your X-Cart license or by removing these addons.
The addons will not be installed, and you will not be able to proceed with the migration process until you upgrade the license or remove the addons.
Step 6 - Transfer
The next step will show you a list of X-Cart entities that will be transfered from your X-Cart 4 to X-Cart 5, because the migration wizard has collected all needed information about them:
If orders are going to be migrated, you will get a warning message about the currency of these orders: The orders will be migrated using the current store currency (Currency symbol - Currency name). You can change the currency here.
You need to make sure that your X-Cart 5 is using the same currency as X-Cart 4. Use the link in the warning message to quickly access X-Cart 5 currency settings (Store setup > Localization, ‘Currency’ tab) to double check the current currency.
If you want to migrate X-Cart 4 orders starting from particular date, it is possible to specify that date using the Migrate orders from date field:
It is possible to skip X-Cart 4’s data that has already been migrated previously by ticking on the Skip previously migrated data option:
More info about this option in ‘Syncing the data’ section.
Click the Start migration button to start the process:
The migration process may take a while to complete and it can only be running while the page is open. Hence make sure to keep the page open or if you have to close it for a while, do not forget to re-open it in order to continue with the process.
While your data is being migrated, you can see the progress on the screen. Here are the stages that have to be completed:
- Migrating data Transitioning the data from X-Cart 4 to X-Cart 5.
- Processing products… Calculating product related data, like bestsellers statistics based on the migrated orders.
- Processing categories… Calculating category related data. The category tree will not be displayed correctly before this step is completed..
- Removing duplicate images… Removing any duplicate product images, in case any of them got duplicated during the migration.
The stages above will be completed in any migration process, regardless of whether you are importing products/categories. If your X-Cart 5 store has products and categories, these processes are simply necessary to ensure that your store will look and function correctly.
Migration Wizard does not do the resizing of images due to the fact that you may want to install another template with different image sizes, so this process can be run in vain. Once you decide what template to use, do the resizing manually by using the Generate resized images button in the Look & Feel > Images section.
Step 7 - Complete
This is the final step of the process, when your data has been successfully migrated.
Please keep in mind that user passwords are not stored in the database. Hence the passwords cannot be transferred safely during the migration process, and all the users will have to reset their passwords using the Forgot password? option on their next login to the X-Cart 5 store.
We recommend adding a special banner to the X-Cart 5 Sign in popup prompting the users to restore their password after the store migration. A sample custom addon that will add a label to the sign-in form can be downloaded here.
In some cases things may not go as smoothly as one would hope during the data migration process. If you experience problems like the process freezing in the middle of migration, increase your server time limit or decrease the migration_chunk_length setting in
If you want to do another migration (e.g. to finish the migration after testing it in the Demo mode), you can restart the migration wizard using the Restart wizard button:
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub.