From X-Cart 4 Classic
Revision as of 09:54, 30 September 2010 by Ivka (talk | contribs) (How to install patches?)
Jump to: navigation, search


Installation and configuration

Where do I download X-Cart?

Click here to download the latest release of X-Cart Gold/X-Cart Pro. More files are available in File area section of your Qualiteam account. Files are supplied in .tgz or .zip archives.

How can I unpack X-Cart distribution archive in Windows?

If you run Microsoft Windows, you can use WinZip (or WinRAR) tool to extract the files.

  1. If you don't have WinZIP archiver, download it from http://www.winzip.com
  2. Launch WinZIP and open X-Cart distributive package
  3. Click on the Extract button and specify your web server root directory.

See X-Cart:Installation page for help on installation.

How to choose a hosting for my store?

Please study the Choosing hosting provider article. Anyway the hosting must comply with X-Cart:Server Requirements (latest X-Cart version).

How do I know which version of X-Cart I use?

You can find out the version of your x-cart installation using one of the following links:


or on the 'Summary' page in the X-Cart backend.

What is Installation error report?

The report indicates that X-Cart installation may not be completed because the web-server is not configured to run X-Cart software. In most cases, you should contact the hosting support to request to change the server settings.

The report has two sections: REPORT - contains information on the errors that may or may not hinder in the installation procedure, PHP INFO - information on the PHP configuration.

You should pay attention to the first paragraph. Note what errors are reported there, critical (CRITICAL ERRORS) or noncritical (NONCRITICAL ERRORS:).

An example of the installation error report:

X-Cart version: Version 4.1.10
Report time: Sun, 29 Jun 2008 13:56:23 -0400
HTTP_REFERER: https://[store_URL]/[xcart_web_dir]/install.php
- MySQL database support is disabled. MySQL PHP extension must be enabled for correct operation of X-Cart application. [CHECK RESULT: Disabled]

There are CRITICAL ERRORS: MySQL application is not installed on the web-server
For now it is not possible to complete the installation until the problem is rectified.
You should contact the hosting support to request help with MySQL setup.

NONCRITICAL ERRORS do not stop the installation and you can complete it.
However, it is recommended to fix the errors too in order to avoid any possible problems in your future store.

Feel free to contact our support team for an advise.

How to change x-cart web-directory after installation is done?

1. Rename the current x-cart directory. Or if you want your cart to be shown in the root, i.e. www.example.com/home.php, you should move the x-cart files to the root folder on the server.

Note: Make sure you make backup copies of the existing files in the root folder if their names coincide with the names of the files being moved from the /xcart directory (for example, index.html), because they will be replaced when you move the files.

2. Update /config.php file (it is located in the root x-cart folder). You should alter this variable

$xcart_web_dir ="/[dir]";

where [dir] is the current x-cart folder. If you just changed the name of the folder, you should insert the new name in [dir].

If you moved the files to the root, change the string thus

$xcart_web_dir ="";
Note: For versions 4.0.x and lower. If the x-cart images are stored in the file system, you should move them to the database before changing the directory. Images storage location is defined in the admin back end, "Images Location" page.

How do I move my images to the file system?

X-Cart 4.0or above

First, you should export images to /files directory of X-Cart. X-Cart requires three images' folders: for icons, for thumbnails and for detailed images. You should create individual directories inside /files for each type of images and indicate corresponding paths on the 'Images location' page in the admin zone. During import of images to file system, X-Cart will overwrite images files names to appropriate ones. For ex., "home/public_html/xcart/files/thumbnails" will be a path to thumbnails images.

Thus, to import images to the file system you should follow the following steps:

1. Create three folders inside /files dir: for ex., "icons", "thumbnails" and "detailed_images"

2. Set 777 permissions on these folders (chmod 777 [folder_name])

3. Go to 'Images location' page in the admin back end and type in the paths to the images such as


4. Choose to store images in 'file system' and click 'submit'.

What is Auth code and where can I find it?

For security reasons, we added Auth code into install.php script. When the installation script detects that X-cart is already installed on your host it will not allow you to proceed without entering the Auth code.

To protect your work, we recommend either deleting script install.php, or changing default Auth code. But it is better to keep install.php since you may need to install different skin sets (X-cart comes with several skin sets).

You will find the Auth code in [xcart_dir]/include/install.php file:

# Put access code here
# A person who do not know the auth code can not access the installations script
$installation_auth_code =

You may change the auth_code at any moment. Also the code is displayed in the admin back-end, on the 'Summary' page.

How to change storefront skin after the installation is done ?

  1. Run the installation script, i.e. open http://[your_store]/[xcart_dir]/install.php in your browser;
  2. Enter the Auth code, you will find it in the include/install.php file and also in the X-Cart admin zone -> on the "Summary" page;
  3. Choose 're-install skin' and click 'next'. You will be offered to select a desired color scheme, layout and dingbats set. Choose a skin you like.
  4. Complete the re-installation and check how your store looks now.

How to replace logo shown on storefront?

Logo can be changed by altering the following IMG tag located in the 'skin1/customer/head.tpl' template (if using default skin):

<IMG src="{$ImagesDir}/xlogo.gif" width="244" height="67" border="0">

Remember to change width and height values with the appropriate ones. For more details please refer to Replacing X-Cart's Logo

Logo shown on invoices can be changed by altering the following IMG tag located in the '/skin1/mail/html/order_invoice.tpl' template:

IMG src="{$ImagesDir}/companyname_small.gif" border="0"

You should upload the appropriate image to /skin1/images' directory.

How to replace logo shown on invoices?

You should replace the logo image in file '/skin1/images/companyname_small.gif'.

As an alternative, you can edit a path to the X-Cart Invoice logo file in template '/skin1/mail/html/order_invoice.tpl'.

Find this code:

<img src="{$ImagesDir}/companyname_small.gif" border="0" >

and replace it with this:

<img src="{$ImagesDir}/new_companyname_small.gif" border="0">

where new_companyname_small.gif is the name of the new logo file. You should upload it before to '/skin1/images' directory.

After that you can edit the image tag in the way you need (change file name, image width, image height etc).

How to set company name?

Refer to X-Cart:Company Options#Company details

Your company name can be set in 'lbl_site_title' language variable.

1. Log in to the admin area 2. Go to the "Languages" section 3. Select a language in the "Edit language" selectbox. 4. Select a topic: Label. ("text" for :txt_, "Errors" for err_) 5. Find the 'lbl_site_title' variable and edit its value in the memo. Alternatively you can just leave the field void. In this case the company name will be the same as it is in the copyright notice. 6. Click the "Apply changes" button.

Note: The company name which appears in Copyright field, in the invoices, etc. does not correspond with the company name on the main page of your store and in the navigation bar above. Actually what you're setting via lbl_site_title' variable is your site's title, which can differ from your company name. You can have any text here. That is why setting of your real company name and this site title are carried out separately. Moreover it helps to make a multilingual company name.

Concerning the company name in the e-mail invoices, it is set via your Admin zone->Administration tab->General settings->Company options->Company name field.

How to change my site title appearing in the admin back-end?

  1. Go to the "Languages" section.
  2. Select a language in the "Edit language" select box.
  3. Find the 'txt_site_title' language variable and edit its value in the memo.
  4. Click the "Update all" button

How can I customize the look of X-Cart storefront?

Refer to X-Cart:Customizing storefront page.

My store says "This is a demo store powered by the X-Cart". Does this mean I am using demo version?

This is a standard welcome message which can be easily modified. If you open the '<xcart_dir>/skin1/customer/main/welcome.tpl' template, you will see following statement there:


When a customer visits your site, the {$lng.txt_welcome} statement is substituted with content of the 'txt_welcome' language variable, i.e. "This is a demo store...".

How to modify the 'txt_welcome' language variable:

  1. Log in to the admin area
  2. Go to the "Languages" section
  3. Select a language in the "Edit language" selectbox.
  4. Select a topic: Text. (‘text’ for :txt_, ‘Errors’ for err_)
  5. Enter 'txt_welcome' in the 'Apply Filter' field to find the variable and edit its value in the memo field.
  6. Click the "Update all" button.

Also, if you start the "Webmaster mode", you will be able to edit language variables in easier way: all you will need is to click the text and edit it. Refer to the manual to learn more about the ‘Webmaster mode’ feature.

How to alter default name titles "Mr.","Mrs.","Ms."?

In X-Cart v4.1.x and later this can be done using 'Administration'-> 'Titles' section in admin back-end.

In previous X-Cart versions, you have to edit '/config.php' file altering the following string:

$name_titles = array("Mr.","Mrs.","Ms.");

How to remove "Powered by X-Cart: shopping cart software" text?

Edit skin1/main/prnotice.tpl template.

How can I obtain a USPS account?

Visit the site http://www.uspswebtools.com and register for USPS Web Tools (click on the ‘Sign up for USPS Web Toos’ link and fill in the registration form). You will receive an e-mail with Username and Password. Follow the instructions provided there. Get in touch with Internet Customer Care Center and ask to switch on your profile to allow you to access the Production Server and to provide you with the production URL (Only the URL without ShippingAPI.dll file, i.e. "production.shippingapis.com").

Enter this URL, username and password into the appropriate fields in the USPS account details subsection of the ‘Shipping options’ page (accessible via ‘General settings’ in the admin area).

How to choose a payment processing service?

The guidelines are available in the Choosing payment gateway article.

How to setup UK shipping and taxes

When you are installing X-Cart by running the installation wizard script, you should select option "United Kingdom" in dropdown "Configuration settings". After the installation is completed, UK-specific configuration will be imported into your store database.

To setup UK shipping and tax on a working X-Cart, you can apply an SQL patch from xcart_web_dir/sql folder - xcart_conf_UK.sql file. Download this file to your machine and install it via the X-Cart admin zone, "Patch/Upgrade" section, "Apply SQL patch" form.

The SQL configuration patches were added in v4.0.x. If you are using one of the earlier versions of this branch and do not find the patch, you can extract it from the fresh distributive of v4.0.x.

Note: The patch does not work on v3.x.x

If you need add specific UK shipping methods you can create them manually. Go to the admin backend, "Management" menu, 'Shipping methods' page and add new methods in the "Defined shipping methods" section.

Does X-Cart support recurring billing?

Beginning from version 4.4.0 X-Cart does not come with built-in X-Cart:Subscriptions module (due to limitations caused by the PCI-DSS standard). 3rd-party services or recurring transactions offered by payment gateways should be used instead.

How to setup X-Cart in PCI-DSS compliant manner?

Please find guidelines at X-Cart:PCI-DSS.

Are there translations available for X-Cart?

Yes, you could find some at:

Where do I edit my "About our site", "Terms & Conditions", "Privacy statement" pages?

The pages in question are embedded static pages.

The content of these pages can be edited on the 'Static pages' page in your X-Cart admin area, for example:


For more detailed information about "Static pages" feature please refer to the Static Pages section.


What is the one-license-one-store rule ?

This means that you are permitted to use one instance (a single installation) of the X-Cart software on one web server and one website only; in the event You intend to use the Software or any part thereof on more than one website, the license for each such multiple use must be obtained.

Examples explaining the one-license-one-store rule:

  1. If your store is accessible from multiple domains but the content is the same for each link, this is OK and does not require multiple licenses.
  2. If your store is accessible from multiple domains but each domain shows a different storefront skin style, this is OK and does not require multiple licenses.
  3. If your multiple stores are located at sub-domains or in sub-directories of the same domain, the license for each store is required.
  4. If your store is accessible from multiple domains and your store is customized to show/hide/alter certain part of content based on the domain, the license for each domain is required. In this situation the stores appear to have separate content thereby making them separate stores in the eyes of the license agreement. The content needs to be the same for each domain in order to qualify as a single store.

How to transfer the license to another party?

X-Cart License agreement allows you to transfer your license to another party. Read how to submit a request to transfer your license.

How to obtain an additional license?

You can purchase an additional license in Buy products/services section of your X-Cart Account:

- click on a necessary product link (X-Cart Gold/X-Cart Pro/LiteCommerce 2.1) - choose add-ons/services, that may be ordered in addition; - click "Continue" button and follow the ordering dialogue.

My store was moved to another domain. Is there anything that I must do pertaining to licensing?

You should change the license URL in your X-Cart Account.

  • go to 'My licenses' section;
  • click 'Change URL' link located next to the license;
  • you will be redirected to the "Change license URL" tab: enter the new license URL in the corresponding field there and tick "I understand that I have to remove the software from old_url within 48 hours after the license is reissued" checkbox;
  • hit 'Change URL' button.

When the records are updated you will be notified by a message (in one business day maximum).


How to upgrade my store?

Common instructions on the upgrading process can be found at X-Cart:Upgrading page.

How to install patches?

Diff file (or a patch) is a file 'describing' changes which needs to be applied to the file. In UNIX world diff files are a standard way to apply changes/fixes to a program source code. There is a special program called 'patch' which reads diff files and applies the changes to the source code. In everyday use diff files are frequently called 'patches' which may sometimes cause confusion.

We suggest three methods for patch installation.

1) Automatic installation via X-Cart admin.

  1. Save the text of the patch as a file.
  2. Log in to the admin area and go to the 'Patch/Upgrade' section.
  3. In section 'Apply patch', select your file by clicking on 'Browse' button. Click 'Apply'.

For more details please refer to Applying Patches via X-Cart Admin area.

2) Running 'patch' command.

  1. Save the text of your patch to a file (e.g. patch.diff).
  2. Copy this file (patch.diff) to the directory where X-Cart is installed.
  3. Issue the command 'patch -c < patch.diff' to check the patch applicability.
  4. If there are no errors during the check-up, apply the patch by issuing the command 'patch < patch.diff'.

You can read more about 'patch' command in the manual (man patch, info patch).

If a patch application failed in the first two ways (this may be caused by redundant spaces or conversion problems) you can try to apply the patch manually, as described below.

3) Incorporate the changes manually right in the source code.

What is diff (patch) file?

Diff (or patch) is a file that displays the changes made per line for text files, and in particular, for X-Cart source files.

Diff can include changes for several files. The name of each modified file is specified under a header line that may look something like this:

Index: include/func/func.category.php

The above header line indicates that the diff displays the changes for <xcart_dir>/include/func/func.category.php file.

Each header line is then followed with one or several "hunks". Each "hunk" starts with a line that may look something like this:

@@ -942,8 +940,7 @@


  • 942 - indicates the number of the first line in the original code (before patch application)
  • 8 - indicates the number of lines in the original code (before patch application)
  • 940 - indicates the number of the first line in the changed code (after patch application)
  • 7 - indicates the number of lines in the changed code (after patch application)

Then follows the file code that includes lines marked with the "+" and "-" signs.

Lines marked with "+" are the lines that you need to add in the file to be patched.

Lines marked with "-" are the lines that you need to remove from the file to be patched.

Example of diff file

Index: include/func/func.category.php
@@ -585,9 +585,7 @@

$cat = abs(intval($cat));

-    $to_search =
-    $search_condition =
-    $join_tbl = array();
+    $to_search = $search_condition = $join_tbl = array();

$from = "$sql_tbl[categories] AS node ";

@@ -942,8 +940,7 @@

-    $search_condition =
-    $join_tbl = array();
+    $search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

General instructions

1. Open the diff file in a text editor.

2. Edit the file (in our example, include/func/func.category.php):

  • Find the lines marked with "-" in the text of the patch and remove them.
  • Insert the lines marked with "+" in the text of the patch.

In our example, the original code (before applying the patch) would look like:

line 585:
line 586:    $cat = abs(intval($cat));
line 587:
line 588:    $to_search =
line 589:    $search_condition =
line 590:    $join_tbl = array();
line 591:
line 593:    $from = "$sql_tbl[categories] AS node ";
line 594:
line 942:        'c.rpos'
line 943:    );
line 944:
line 945:    $search_condition =
line 946:    $join_tbl = array();
line 947:
line 948:    if ($current_area == 'A' || $current_area == 'P') {
line 949:

Total lines: 9 and 8 in each hunk correspondingly.

The changed code (after applying the patch) would look like:

line 585:
line 586:    $cat = abs(intval($cat));
line 587:
line 588:    $to_search = $search_condition = $join_tbl = array();
line 589:
line 590:    $from = "$sql_tbl[categories] AS node ";
line 591:
line 940:        'c.rpos'
line 941:    );
line 942:
line 943:    $search_condition = $join_tbl = array();
line 944:
line 945:    if ($current_area == 'A' || $current_area == 'P') {
line 946:

Total lines: 7 and 7 in each hunk correspondingly.

Understanding the process

In simple words, the patch application procedure for each hunk is as follows:

  • Search for the code to be replaced around (above and below) the expected line.
  • If found, change it to the new code.

Let us take another look at the second hunk of the example patch provided above to understand the process:

@@ -942,8 +940,7 @@

-    $search_condition =
-    $join_tbl = array();
+    $search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {
  • Original code to search for (8 lines of code around the line 942):

$search_condition =
$join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

  • New code to change to (7 lines of code):

$search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

The built-in patch/upgrade utility basically works in the same way.

If you cannot apply the patch in these ways it means the file that needs to be patched has been modified or this file is from another version of X-Cart and cannot be patched by this patch. Ask technical support to help you.

There are upgrade patches in my file area, what are they for and how can I use them?

Starting with v3.2.0 a special upgrade engine, allowing upgrading to a newer version, was implemented in X-Cart. Detailed instructions on how to perform upgrades come in the upgrade packages in UPGRADE.readme files.

Upgrade patches are a set of files which describe differences in code between old and new versions. All the changes are represented in standard diff format (UNIX unified diff format). Diff files contains structured data indicating what pieces of code are to be added/replaced/deleted: a sample of old code and a new code to insert instead. You will find more information about diff file at http://www.gnu.org/manual/diffutils-2.8/html_chapter/diff_toc.html

The main advantage of this approach is that diff patch technique allows upgrading even customized versions of X-Cart: X-Cart upgrade engine follows the list of files from the file file.lst and tries to patch them. Then database upgrade is fulfilled. If the code is not changed the upgrade will be successfully completed. However, since X-cart is highly customizable product most of X-cart users are certain to modify its code and templates to meet their needs. Here might come difficulties. If a piece of the code to be patched was customized (altered), the patch engine won't patch it and the upgrade script may fail. You will be notified about it by the system. So if you have ever changed X-Cart code you should be prepared to resolve the conflicts manually.

X-cart patch engine creates a log file that reflects a progress of the patching process - templates_c/upgrade/patch.log. The failed hunks are stored in reject files filename.ext.rej. Using this information you can figure out what parts of code haven't been patched in order to patch them manually afterwards.

For more information on the upgrade procedure and the instructions, refer to the manual included into the upgrade archive.

Why I'm getting checksum errors during upgrade?

Firstly, if you use WinZip to extract files from the upgrade/distribution kit, you need to change the default configuration in the following way: Click Options, Configuration, select the Miscellaneous tab and remove the tick from 'TAR file smart CR/LF conversion'. After that unpack the files from the archive once again and re-upload the files to your server.

Secondly, when you use FTP for uploading text files on the server it may alter your files (if it's in 'ASCII'/'Text' mode). It replaces the line-break symbols that are different for Unix and Windows systems whereas all the other text is left the same. These changes are not visible, but X-Cart checks files checksum and the values appear different from the expected ones. In order to solve the problem you should set your FTP client in the 'Binary' mode and re-upload the upgrade package files on the server.

Basic usage

How to edit multiple products at once?

You may want to use 'Search-and-modify' feature: - open 'modify product' page; - check 'Select-and-modify' check-box and make a search for products; - in the 'product details' section, tick boxes near necessary settings, change the values and save.

As a result the change will be applied to all the found products at once.

How to turn off display of featured products list?

You should modify the '/customer/main/welcome.tpl' file. Comment out this part of the code:

{include file="customer/main/featured.tpl" f_products=$f_products}

i.e. change it to

{* include file="customer/main/featured.tpl" f_products=$f_products *}

This will hide the 'Featured products' section.

How to work with 'webmaster mode'?

Webmaster mode allows you to edit templates within the admin interface. You may edit language variables (denoted as "$lng.XXX" in templates) by changing those values in WYSIWYG mode.

1) Before entering the webmaster mode, close any template windows & label windows. Enter your admin zone, go to the 'Administration' menu, 'Webmaster mode' page. Click on 'Start webmaster mode' button.

2) The additional "templates" window will appear. It displays the list of templates composing a current page. You can call the template editor from this window by clicking a template.

3) Go to the page you want to change. To define the right template, look at the browser status line (at the page bottom). When the mouse is pointing at some text, this status line indicates the corresponding template and label.

4) To change a label, click on it. If the label is under a hyperlink, move the mouse over it and press "e" (Edit) on the keyboard. The label dialog will appear.

5) After you set a new label content you can

(a) preview the site with the changed label,
(b) save the text in the database, and
(c) copy the label name into the clipboard (IE only).

6) The webmaster mode is based on sessions: it applies only to the computer it has been set up on. I.e., when the 'Webmaster mode' is launched, it isn't displayed at the customer's end and doesn't affect the store performance. The changes will show up only after the admin clicks on 'save' button.

7) To quit the webmaster mode, go to admin zone, to the 'Administration' menu, 'Webmaster mode' page. Click on "Quit webmaster mode" button.

Note: Note:Webmaster mode will not work with compiled templates.

For additional information about Webmaster mode please refer to this article.

How to mark up all our product prices at once?

You can use the below SQL query to mark up all the product prices, let's say 20%:

UPDATE xcart_pricing SET price=price*1.2;

The query can be applied on "Patch/Upgrade" page in X-Cart admin back-end:


After the patch is applied, please force (re)generation of cache files and quick tables via the 'Summary/Tools' section of your store's Admin area.

Note: It is recommended to back up your X-Cart database before applying SQL patches.

Where now?

I want to share my X-Cart experience with other people. How can I do that?

We welcome any kind of feedback (positive or negative) about our product as valuable information that can help us to improve it.

We welcome you to share your X-Cart experience with other people on the following web-sites:

Please answer the following questions in your review of X-Cart:

  • What was your 1st impression of X-Cart?
  • What was your impression of X-Cart after you passed the learning curve?
  • Is it making your life/profession easier or harder somehow?
  • What do you value most about X-Cart?
  • What do you dislike most about X-Cart?
  • If your web-site is live now can you say that X-Cart helps you to increase your sales?

I'm experiencing problems. Where can I find a solution?

  • Try to search this website for the solution.
  • Try to find out more about the problem, see How to debug X-Cart or see the section below for information on how to contact Qualiteam engineers and other knowledgeable users.

I've found a bug or have a feature request. Where do I post it?

If possible please search the database prior to posting, to avoid creating duplicate entries.

I have a question not answered here. Where do I ask for help?


How do I change or reset my admin password? (I lost it)

1. If you can log in to your X-Cart admin area using another account, please do so, and reset/modify the other admin password as needed.

2. If you cannot remember your admin password, there's still hope.

The first thing you can try is to click the "Forgot password?" link from the admin area home page, for example:


or just go straight to the Password Recovery page, for example:


Enter the admin username and email address, then submit the form. Your account information will be mailed to you shortly.

3. If for some reason that doesn't work for you, you can create a temporary admin account in order to log in.

Open your phpMyAdmin (supplied by your hosting company), click the "SQL" tab and run this query:

X-Cart Gold edition

DELETE FROM xcart_customers WHERE admin_name = 'mytempadmin';
INSERT INTO xcart_customers (login, password, usertype)
VALUES ('mytempadmin', 'mytempadmin', 'P');

X-Cart Pro edition

DELETE FROM xcart_customers WHERE admin_name = 'mytempadmin';
INSERT INTO xcart_customers (login, password, usertype)
VALUES ('mytempadmin', 'mytempadmin', 'A');

You should now be able to log in using the following details:

  • Username: mytempadmin
  • Password: mytempadmin

After you log in, remember to delete this temporary admin account and reset/modify the other admin password as needed.