X-Cart:Egoods

What Egoods module does

The Egoods module enables you to sell digital products like software, audio and video files, graphics, etc. that are delivered to customers by download.

When the module is enabled, every Product details page in the Admin and Provider areas contains a special field ESD distribution that enables you to assign a file to a product. After you have specified a file for the product and saved the product details, X-Cart handles this product as a downloadable one: the system does not calculate shipping charges and disables inventory tracking for the product.

Customers can add digital products to their carts and go to checkout in the same manner as if it were ordinary products. After an order, containing such a product, has been processed, X-Cart sends an email notification with a download link to a customer who placed the order. The customer can then follow the link and download the product. Each download link is valid for a limited time, defined by the store administrator. When needed, the store administrator can manually extend the download period.

Egoods is available as a built-in module in all X-Cart editions. It does not require installation and can be enabled in the Modules section of X-Cart Admin area.

Roles in Egoods module management

If you are an X-Cart GOLD or GOLD PLUS administrator/provider or an X-Cart PLATINUM or PRO administrator, you can:

• Enable/disable Egoods module and adjust its configuration (see section #Enabling and Configuring 'Egoods').
• Upload files for downloadable products to any location in the X-Cart file repository.
• Limit available payment options for orders containing downloadable products.
• Assign files to downloadable products.
• Extend expired download links.

If you are an X-Cart PLATINUM or PRO provider, you can:

• Upload files for downloadable products to a personal location within the X-Cart file repository.
• Assign files to downloadable products.

Enabling Egoods module

Before you can start creating downloadable products you must enable the Egoods module in the X-Cart Admin area.

To enable the module:

1. Log in to the Admin area.
2. Go to the Modules section (Administration menu -> Modules).
3. Select the check box for the entry Egoods.
4. Click the Update button at the bottom of the page.

Configuring Egoods module

To configure the module:

1. Log in to the Admin area.

2. Go to the General settings section (Settings menu -> General settings).

3. Click on the Egoods link (General settings/Modules options). You will be redirected to the Egoods configuration page.

4. Use the Egoods form to adjust module settings.

• Download key TTL (hours): The number of hours after a download key was sent to a customer, during which the key is valid and the customer can download the product.
• Disable online payment methods for orders containing egoods: Use this option to disable all online payment methods in your store if an order contains a downloadable product.

If you select this check box, all online payment methods will be disabled, and customers who buy downloadable products in your store will be able to pay through offline payment methods only (those that require manual processing of payments). Remember to activate at least one offline method.

If you leave this check box unselected, customers who buy downloadable products in your store will be able to pay, using any active payment method.

• Disable payment methods without manual processing or 'Auth only' mode for orders containing egoods: Use this option to disable those online payment methods in your store which do not support 'Auth only' mode if an order contains a downloadable product.

If you select this check box, the online payment methods which do not support 'Auth only' mode will be disabled, and customers who buy downloadable products in your store will be able to pay through those online payment methods which support the "auth only" mode or through offline payment methods which require manual processing of payments.

If you leave this check box unselected, customers who buy downloadable products in your store will be able to pay, using any active payment method.

Important: If you choose to enable only those payment methods that require manual processing or support the "auth only" mode, remember to leave the Disable online payment methods for orders containing egoods check box unselected. Otherwise online payment methods, supporting the "auth only" mode will also be disabled.

• Allow brute file size estimation: Select the checkbox to allow size estimation of remote files by reading the whole file if alternative ways of estimating file size cannot be used.

Warning: having this option enabled will increase your server traffic.

5. Click the Save button.

Managing Product Files

Arranging file location

Files for downloadable products can be physically located either on the same server as your copy of X-Cart, or on a different server. The recommended option is to store files on the same server. This way of arranging the file repository has the following advantages:

• The store does not depend on other servers, which may be temporary down, and individual URLs, which may be broken;
• Incoming and outgoing traffic is spent more efficiently;
• Customers can download files faster;
• Files can be assigned to products by simple browsing;
• Files can be uploaded to the file repository directly from the X-Cart Admin and Provider areas.

However, for some reason or another, you may have to keep some files on a different server. In such a situation, make sure that the files on the other server(s) can be freely accessed through the internet, e.g. a firewall will not reject the connection, etc.

When storing files on the same server, the default location for the file repository is the /files directory in the X-Cart root directory.

Note: In X-Cart GOLD and GOLD PLUS editions, all files for downloadable products are stored in a single location (within the file repository), which can be accessed by any user with the administrator/provider privileges.

In X-Cart PLATINUM and PRO editions, each provider has a personal location within the file repository. So, depending on the number of providers registered with the store, the /files directory may contain one or more folders. Each of these folders stores files uploaded by the respective provider only. One provider cannot manage and use other provider' files. Store administrators can manage all files and folders within the /files directory.

Please also note that in X-Cart PLATINUM and PRO store administrators can assign any file to any product of the provider in whose file folder the file is stored, however they cannot assign a file of one provider to a product of another provider.

Note: For 4.3.x and older versions, the provider's personal file repository is located within the /files/[provider_username] directory; for example, /files/provider.

For 4.4.x, the provider's personal file repository is located within the /files/userfiles_[USERID] directory, where [USERID] is the number that corresponds to the user ID of the provider. For example, /files/userfiles_1.

The user ID can be found in the URL of the modify profile page, for example:

http://www.example.com/xcart/admin/user_modify.php?user=3&usertype=P

where "3" is the user ID.

You can upload files to the directory (or its subdirectories) through the X-Cart Admin and Provider areas, or you can upload them in bulk via FTP, SCP or other suitable facility. For instructions on how to upload files through the X-Cart interfaces, refer to the X-Cart:Files section of this manual.

If necessary, you can assign the file repository to a different directory within the X-Cart root. You can do it by editing the main X-Cart configuration file config.php.

Important: When assigning the file repository to a different directory, you need to transfer/copy the files and folders from the original directory to the new directory manually using the available file management facilities. Otherwise the structure and content of the original directory will be lost.

To change the default file repository location:

1. In the X-Cart root directory, locate the file config.php and open it for editing with your favorite plain text editor.

2. Change the values of variables $files_dir and $files_webdir.

3. Find the following lines.

$files_dir = "/files";
$files_webdir = "/files";

4. Replace the directory name, which is enclosed in quotation marks, with the name of the new directory.

Important: The values of the variables $files_dir and $files_webdir start from forward slash ( / ), which means that the path is relative to the X-Cart root directory. Remember to keep the slash when changing the value of the variables.

For example, if you want to store files in the directory called "download", edit the values as follows.

$files_dir = "/download";
$files_webdir = "/download";

5. Save the changes.

Protecting files

It is important to protect files for downloadable products from unauthorized access. The directory /files, a default X-Cart location for the file repository, already has correct permissions and is set up to protect its contents. If you keep files in a different directory (regardless of its actual location), make sure the directory is well protected. On an Apache-based server use an .htaccess file. On an IIS server use the Access permissions dialog box.

For more information on how to protect files and directories, refer to the documentation for the server you use.

Handling Products and Orders

Adding downloadable product

Adding a downloadable product is very to similar to adding an ordinary product, which is described in the Adding Products section of this manual. The only difference regarding downloadable products is that you must also assign a file to a product using the ESD distribution field in the Product details form in the Admin/Provider area.

To assign a file to a product:

1. Create, import or clone a product as described in the Adding Products section of this manual.

2. At the Product details page, locate the field ESD Distribution.

3. Assign a file to the product.

If the file repository is in the X-Cart root directory (by default the directory /files )

a) Make sure the file is uploaded to the file repository.

b) Click the Browse... button.

You will see a form that enables you to select a file.

c) If necessary, change the directory.

d) Select the required file from the list and click the Select button.

If the file repository is outside the X-Cart root directory, or the file is located on a different server

a) Make sure you know the correct URL of the file.

b) Put the absolute URL of the file into the the ESD Distribution field.

For example, if X-Cart is installed to the directory public_html/xcart/ while the files for downloadable products are located in the directory public_html/download/, the URL must look like http://www.example.com/download/product_filename where product_filename is the name of the file, assigned to the product.

4. Click the Save button.

Processing orders

Your store customers can pay for downloadable products, using any of the available payment options, including both online and offline methods. A few minutes after an order with a downloadable product has been processed, a customer, who placed the order, receives an email message ( 'Order is processed' notification) with a download key (a link like http://www.example.com/xcart/download.php?id=920e98f7d889eb7781a). The customer must then follow the link and download the product before the key has expired. The expiration period, which is also referred to as TTL (time to live), is defined by the store administrator on the module's configuration page. The TTL countdown for a download key begins immediately after the order has been processed and X-Cart sent a message with the key. An order is considered to be processed after its status has been changed to "Processed". Order statuses can be changed either manually by the store administrator or automatically according to a response that X-Cart receives from a payment gateway, which actually processes online payments. For a more detailed description of how X-Cart handles orders and order statuses, refer to the Orders section of the manual.

Due to the specificity of how digital products are delivered, the Egoods module enables you to have more control of how orders with digital products are processed: You can disable all online payment methods, which mostly provide for automatic order processing; or you can choose to enable only those payment methods that require manual processing or have the "auth only" mode. The "auth only" option means that a payment gateway does not really withdraw the order total from a customer's credit card, but it only checks whether the sum is available and temporarily freezes this money until a later time, which is limited by the terms and conditions of the payment gateway. The store administrator can then either capture the authorized amount or void it. As soon as the reserved money is captured, the order gets processed and X-Cart sends a download key to the customer.

This way of processing orders that contain downloadable products, as well as using other methods that require manual order processing, allows you to filter suspicious and potentially fraudulent orders and approve only trustworthy purchases.

Important: X-Cart does not automatically change the order status, depending on whether the product has been downloaded or not, as X-Cart does not track that kind of customer activities.

Extending download period

If necessary, the store administrator can extend the download period for products by prolonging the TTL (time-to-live) limit of download keys.

To prolong the TTL limit of a key:

1. Log in to the Admin area.
2. Open the order details page for the order that contains the download key you want to prolong.
3. Click the Prolong TTL button at the bottom of the Order details form.

Clicking on Prolong TTL will extend the download period of all downloadable products in the order for another period. The length of the period is defined by the store administrator at the module's configuration page. For details, see the #Enabling and Configuring 'Egoods' section of this manual.

Troubleshooting

Getting an error when trying to download Egoods

Error message: "You supplied valid download key, but system failed to find distribution package, please contact the shop administration".

Solution:

If the file for your downloadable product is stored in the X-Cart root directory (by default the directory /files) - make sure the file is located in the proper directory within the X-Cart's file repository.

If the file for your downloadable product is stored outside the X-Cart root directory, or the file is located on a different server - make sure the URL provided in the field "ESD Distribution" is correct. Besides, make sure that the files on the remote server can be freely accessed through the Internet, e.g. a firewall will not reject the connection, or the remote server is not down, etc.