web design and hosting
features and pricing my account customer support about ICG Link, Inc. contact ICG Link, Inc.

NetMerchant Shopping Cart
   
 
 
NetMerchant is a full service shopping cart. It has a basket where you put goods prior to checkout and can ship using a variety of options.

IMPORTANT NOTE: While the NetMerchant cart is still functioning just fine, it was built starting in the mid 90's and has reached the sunset of its years as technology has advanced. We have halted further development and debugging of the system and recommend you contact us for more modern alternatives.

However, if you still want to dive in, use the example at the bottom of this page to see how it works.

Explanation

NetMerchant is fairly simple to use once you understand what's happening. You must sign up for secure server to use this system. When you do, a folder called sweb will be created on the same level as your www folder. Just as any file located in your www folder is found as http://www.yourdomain.com/filename, any file located in you sweb folder is found as https://secure.icglink.com/yourdomain/filename.

Before you start, you should understand how ecommerce works and review our secure server procedures. NetMerchant has three primary scripts that work together to produce a secure order. Once your cart is set up, you can use our specials and discounts system to enhance your shopping options and our file selling feature to sell files rather than products on-line.
  • basket.pl: This script keeps track of the items you order prior to purchase. You can add things to your shopping cart or simply check what's in your cart by calling this script and you can change the quantities of items in your cart by calling it.
  • order.pl: This script keeps track of your order. Once you have your basket full and are ready to check out, you will enter your shipping and billing information using this script. You can edit your shipping or billing information after you have entered it by calling this script.
  • purchase.pl: This script allows you to check out. It takes the information you entered using order.pl and basket.pl and processes it. Purchase.pl can do the following things:
    • write to log files in your secure data directory or to an SQL database
    • send mail telling you about the order
    • process your order using PayPal, Cybercash, AuthorizeNet or Quick Commerce
There are just four basic steps to setting up your on-line store. Here is an outline of the four basic steps and other options available.
  1. Set up the shop templates.
  2. Customize the templates to meet your needs.
  3. Create your product list.
  4. Call the cart from your product pages.
  5. Options & Further Details
Step 1

Your first step is to choose a shop name for your shop and create a folder under your www/data folder with that name. The NetMerchant scripts use several html template files to display information and text files to perform calculations. These files will have to be located in the www/data/shopname folder where shopname is the name of your shop. In this example, the name we use is "testshop".

In order to make this process easier, we have provided a setup tool that copies default template files to your www/data/shopname folder. You can then edit these files to make NetMerchant look like the rest of your site and perform with the options you need for your particular shop. You may visit the setup tool once you have read these instructions and are ready to get started.

Step 2

Your second step is to modify the text files and template files that NetMerchant uses. Shown below are the six html template files a typical shop will need. Click on each one to learn how these template files work and see what you need to modify so they fit the needs of your particular shop. The setup tool will copy the files to your www/data/shopname folder. FTP the files to your computer and make the replacements shown in the instructions for each page to tailor them to your shop.
  • basket.html - where your basket information is presented and edited (uses insecure images)
  • shipping.html - where you will enter or edit your shipping information (uses secure images)
  • billing.html - where you will enter or edit your billing information (uses secure images)
  • confirm.html - where order info is displayed just prior to purchase (uses secure images)
  • receipt.html - where your order receipt is shown after purchase (uses secure images)
  • error.html - an error page called to display errors along the way (uses secure images)
Below are the text files you will need so NetMerchant can make calculations correctly. The setup tool will copy these files to your www/data/shopname folder and you can FTP them to your computer and make the changes necessary to tailor the files to your needs. Step 3

For your third step, you will have to create a table of all your product information. You can use a simple tab delimited text file for this purpose or if your web site uses SQL, you can use a table in your SQL database. Either way, in these instructions we will call this information the "shop" database. Regardless of which method you use, you must create a file with the name shopname.data that is located in your www/data folder.

3a. Using a Flat Text File for Products

If you use a flat tab delimited text file for your NetMerchant shop database, the first four columns must be exactly what NetMerchant expects. Other columns can be added as needed... for example, you might plan to use the same database with the search script to deliver product information sorted by category, etc. to your visitors. The first four columns are 1) Unique Item Number (see note below), 2) Description (this is the short description that will show up in the cart when a product is purchased) and 3) Price (as a number without $). Optionally, if you want to ship based on weight or by item (see shipping for more information), you will have a fourth column 4) Weight or Item Shipping Cost (as a number). Should you decide not to ship by weight or item, you might wish to leave the fourth column blank for later use. If you do use it for some other purpose, NetMerchant will ignore the data from this column. For example, we have a "testshop.data" file that looks like this:
   JA841        Jacket         64.95    3.5
   PK304        Parka         109.95    2.5
   SS994        T Shirt        11.99    1.32
   MS277        Muscle Shirt    9.95    1.12
   LP271        Pants         135.95   10.2
   TV381        Vest           32.95    5.3
3b. Using an SQL Table for Products

If you use an SQL table instead of a flat file to deliver your product information for NetMerchant, you will be able to manage product inventory and integrate more fully with the rest of a database driven web site. To do this, your flat file must simply contain the following single line:
   DSN
Then you will need to create a DSN or Data Source Name using the tool we have built for this purpose. Log into the link below with your domain name and admin password. You will need the name of your shop, your database name and the name of the table you plan to use for NetMerchant inventory management.
https://secure.icglink.com/cgi-bin/dsnmaker.pl
Now all NetMerchant needs to know is which columns to read and what options are being used and it gets this information from a configuration file with the following name: /www/data/shopname/inventory.conf which should be constructed as shown below. The first three items are required:
   itemno_column     columnname     #The unique item number 
   itemname_column   columnname     #The description as it will appear in the cart 
   itemprice_column  columnname     #The price of the item as a number, no $ 
   itemship_column   columnname     #The shipping charge or weight. It must be numerical only 
   iteminv_column    columnname     #The actual inventory for the item. 
   update_inventory  y/n            #Update the inventory column when an order is placed? 
   nostock_order     y/n            #Allow orders when stock is 0 or negative? 
   negative_inv      y/n            #Decrement inventory into negative numbers (n stops at 0) 
   flag_zerostock    y/n            #Include - OUT OF STOCK - in the item name when inventory is 0 or less? 
   flag_instock      y/n            #Include - IN STOCK - in the item name when an item is in stock. 
   flag_numstock     y/n            #Include - X IN STOCK - in the item name when an item is in stock.
   text_zerostock    BACK ORDERED   #if flag_zerostock is y, this text will be used instead of OUT OF STOCK
and that's it! NetMerchant takes care of the rest.

Note About Item Numbers: One unique item number can not be a subset of another one. For example, you can not have an item numbered 3 and another one numbered 30. A good way to be sure this never happens is to make sure all your items have the same number of characters. Now is the time you should also set up any specials and discounts you may wish to add to your products.

Step 4

For your last step you must call the cart from your shopping pages. In order to add an item to your shopping cart, you simply call basket.pl using the appropriate syntax shown later and call the item number with a c_ before it. This will become more clear as you walk through the example. Since your items are already in a database, it's easy to use the search script to have an interactive product search. You can add additional columns after the fourth colum for such items as a category, long description, size, color, or other information.

Modifiers

Modifiers are optional further enhancements of an item description you might need for an order that doesn't change the uniqueness of the item (doesn't require a unique number). For example, color might be required to fulfill an order, but might not require an entirely new item number. You can add an unlimited number of modifiers called modifier1, modifier2, modifier3, etc. The values of these will show up in your shopping cart and e-mail order. Here's an example with and without a modifier.

Without modifier With modifier
<form action="/cgi-bin/basket.pl/testshop?basket.html" method="post">
<input type="hidden" name="c_JA841" value="1">
<input type="submit">
</form>
<form action="/cgi-bin/basket.pl/testshop?basket.html" method="post">
<input type="hidden" name="c_JA841" value="1">
<input type="hidden" name="modifier1" value="Red">
<input type="submit">
</form>


Note: You can call multiple products with a single form submission by including them within a single set of form tags. However if you do, replace modifier1 with m1_itemno where itemno is your item number. Otherwise NetMerchant won't know which product modifier1 refers to.

Be certain that you keep modifier text simple and short. These are not designed to be lengthy text fields with odd characters such as apostrophe or single quote. To use that type of information, please see special variables below.

Security, Cookies & Referers

During the ordering process, NetMerchant uses referers to jump from the un-secure to the secure server. After that it uses cookies to track sessions in the secure area. Credit card and other order related data are stored on our secure server in encrypted files, not in the cookie. The cart stores a unique session identifier as a cookie on the shopper's computer for 180 days. When the shopper returns to NetMerchant with more items, NetMerchant can add those items to the same cart because it reads the cookie and knows this identifier. Once the shopper checks out, the identifier is deleted from the system and the cookie expires from their machine. If a shopper turns cookies off, NetMerchant can take one of two courses of action at your discretion.
  • Default: By default, NetMerchant doesn't try to use other methods to keep track of the cart if a shopper turns off cookies. The shopper can purchase a single item and check out, but if they try to return to the cart with another item, the previous item and any other order related information will not be remembered.
  • Disabled Cookies: Alternatively, if absolutely necessary, you can enable a backup method for remembering the shopper's information in the event a visitor turns off cookies. The backup method raises a serious security issue because it has to use IP address and browser type to try to identify the shopper. If two people both have cookies turned off and log in with the same IP address and browser type within a 180 day period, NetMerchant can't tell them apart and show one shopper's cart information to another shopper. As long as a shopper has checked out, only billing and shipping information are shared, but if a shopper has entered his credit card number and abandoned a cart without purchase, that number is also remembered. While not recommended, the code to allow use of the backup method is as follows: <input type="hidden" name="no_cookies" value="ok">.
  • Blocked Referers: If your visitors are reporting problems putting items in their carts, they might have a personal firewall installed that is blocking referers. Referers are completely benign and are actually very helpful to your browsing, but some newer third party firewalls and very high settings in IE will block them by default. The referer is the address of the page you came from when you clicked on a link. It is used by NetMerchant when going to the basket to figure out which domain the visitor is coming to the cart from. The way to work around this issue is to add the domain to every call to the basket. That means every product "Add to Cart" button and any "View Cart" button needs to have the following hidden field added: <input type=hidden name=b_own value=yourdomain.com>
  • . Alternatively, you can suggest to visitors that they enable referers, which they should do anyway.
Special Variables

On occasion you may need to customize NetMerchant to do some special discounts or other tricks. The following variables are available for any special applications you might have, but they are not needed for a standard NetMerchant configuration.
  • On the basket page, you may wish to use a button to remove an item rather than use the standard "Update" button supplied with the standard templates. If so, use the following button code: <input type=submit name="del_<! ITEMID>" value="Remove">. You may use both the edit button and this remove button if you wish.
  • <! TOTALQTY> - adds the sum of all the item quantities
  • <! MODIFIER1>, <! MODIFIER2>, <! MODIFIER3> - delivers each individual modifier rather than the standard <! MODIFIER> which provides all modifiers strung together, delimited by commas.
  • <! IP_ADDRESS> - delivers the IP address of the purchaser.
In addition to the above variables, you can pass regular variables from your product pages through your cart all the way to the end of the purchasing process. For example, you might wish to track a code that tells you where a purchaser came from. Once you get the code on the purchase page, enter it as a variable between the form tags that define the buy button. Pass this variable with into the cart and into the shipping page. Once there, populate a v_ variable with the code and it will be carried throughout the process. Please see the shipping information page for more information on OPTIONAL FIELDS.

Examples

Because we use this example for several scripts, we have built a searchable database of products for an on-line clothing store that feeds our NetMerchant example. (You don't have to have a searchable database to use NetMerchant, so we have included second and third examples that cover NetMerchant in the simplest way. Example 1 shows what you can do by blending our scripts.)
Example 1.
Search our on-line clothing store and add a product to your cart.
The database contains three categories of products with two products in each category and three sizes for each product. We won't include the code for the search because that's not relevant to NetMerchant, but we will show you the appropriate NetMerchant code when we get there. You can see the search code in the search script instructions.
Select a category:


Example 2.
Buy a jacket directly.
If you'd rather just get right to the good stuff and pop an item straight into the cart, enter your quantity and press the button below to add a jacket to the cart and bypass the product search. Here's the code for this example. You can see that basket.pl is called and looks in the data file called testshop.data (shown above) in your www/data directory. The html file it will use to display the basket is called basket.html.

<form action="/cgi-bin/basket.pl/testshop?basket.html" method="post">
Qty <input type="text" name="c_JA841" size="2">
<input type="submit" value="64.95">
</form>
Qty:

Example 3.
Skip the Quantity.
If you have no need to allow users to enter a quantity, you can set the quantity simply by giving a value to a hidden field as shown below:

<form action="/cgi-bin/basket.pl/testshop?basket.html" method="post">
<input type="hidden" name="c_JA841" value="1">
<input type="submit" value="64.95">
</form>
ICG Link, Inc. 7003 Chadwick Drive, Suite 111, Brentwood, TN 37027