Last Update: March 1, 2004
Version 3.6


Copyright (c) 1997 - 2002; Microburst Technologies, Inc.
All Rights Reserved.





Table Of Contents
1. Introduction Section 1
2. Features Section 2
3. System Requirements Section 3
4. Steps In Creating An Online Store With uShopTM Section 4
5. Setting Up Directory Structure Section 5
6. Setting Up Store Pages/Applets Section 6
   6.1 Input Applets Section 6.1
   6.2 JavaScripts Section 6.2
7. Special Applets Section 7
   7.1 Shopping Cart Applets Section 7.1
      7.1.1 Shopping Cart Template Section 7.1.1
   7.2 Initialize Applet Section 7.2
   7.3 Search/Browse Applets Section 7.3
      7.3.1 Data File Format Section 7.3.1
      7.3.2 Product HTML Template Section 7.3.2
   7.4 Discount Applets Section 7.4
   7.5 Order Button Applets Section 7.5
8. Transferring Store Pages and Class Files To Server Section 8
9. Creating and Customizing Order Forms Section 9
   9.1 General Order Form Template Section 9.1
   9.2 Credit Card Template Section 9.2
   9.3 Electronic Check Template Section 9.3
   9.4 Bank Template (German Version Only) Section 9.4
10. Installing/Customizing The CGI Script Section 10
11. The uShop Control Panel Section 11
   11.1 General Settings Section 11.1
      11.1.1 Store Information Section 11.1.1
      11.1.2 Order Form Section 11.1.2
      11.1.3 Payment Options Section 11.1.3
      11.1.4 Taxes and Shipping Section 11.1.4
      11.1.5 Email Notifications Section 11.1.5
      11.1.6 Miscellaneous Section 11.1.6
   11.2 Coupon Manager Section 11.2
      11.2.1 Adding Coupons Section 11.2.1
      11.2.2 Deleting Coupons Section 11.2.2
   11.3 Affiliate Tracking Section 11.3
      11.3.1 Add Affiliate Section 11.3.1
      11.3.2 Edit Affiliate Section 11.3.2
      11.3.3 Delete Affiliate Section 11.3.3
      11.3.4 Edit Affiliate Log Section 11.3.4
      11.3.5 Clear Affiliate Log Section 11.3.5
      11.3.6 Affiliate Reports Section 11.3.6
   11.4 Order Reader Section 11.4
      11.4.1 Reading Orders Section 11.4.1
      11.4.2 Deleting Orders Section 11.4.2
   11.5 Diagnostics Section 11.5
12. Testing Your Store Section 12
13. Troubleshooting Section 13
14. Tax Examples Section 14
15. Shipping Examples Section 15
16. Handling Examples Section 16
17. Linking Options Section 17
   17.1 Affiliate Linking Section 17.1
   17.2 Coupon Linking Section 17.2
18. Internationalization Section 18
19. Creating Your Own Java Applets Section 19
20. Creating Your Own JavaScripts Section 20
21. CD-ROM Catalogs Section 21
22. Other References Section 22






1. Introduction
uShopTM is an online shopping system designed to make online shopping the way it should be...easy and intuitive for both the shopper and the web page designer!

uShopTM consists of a series of Java Applets and JavaScripts that together make a flexible frontend to a powerful Perl CGI script. These Java Applets and JavaScripts have been designed to plug easily onto any web page - thus giving you almost total creative freedom when designing your web pages. No longer do you have to hassle with complex forms and complicated CGI scripts. No longer are you limited to particular page layouts and obscure page navigation schemes. With uShopTM, the only limitation is your imagination!


2. Features
Features of uShopTM include:

  • Complete flexibility in designing pages and page layouts.


  • A large collection of Java Applets and JavaScripts that can handle a variety of product options and pricing.


  • A programmer's guide to assist with the development of your own custom Java Applets and JavaScripts that interface with uShopTM.


  • Various tax options including the ability to handle multiple tax rates in the same state and the ability to write your own tax equations.


  • Various shipping and handling options including the ability to setup shipping tables and formulas based on the weight, quantity, or subtotal and the ability to write your own shipping equations.


  • The ability to remember customer information (via cookies) so that returning customers do not have to fill out the order form information again.


  • The ability to handle various payment options including payment by Credit Card, Electronic Check, Bank Transaction (German Version Only), Cash On Delivery, Print (for mail or fax orders), and even a "Contact Me" option.


  • Built-in interfaces to LinkPoint, Authorize.Net, Planet Payment and *PayPal credit card processing systems.

    See http://www.uburst.com/uShop/interfaces.html for the latest information on uShop's Payment Processing Interfaces.

    *PayPal interface available at additional cost.


  • Various discount options including a built-in Coupon Manager that allows you to create coupons with expiration dates.


  • Special "Search" and "Browse" applets that allow you to setup bar-delimited data files from which product pages can be dynamically generated.


  • A built-in Affiliate Tracking System.


  • Built-in Diagnostics to assist with troubleshooting.


  • No monthly fees! Once you buy uShopTM it yours! Note that an additional license must be purchased for each additional store that you setup using uShopTM.


  • And much, much more!

3. System Requirements
The system requirements of uShopTM are as follows:

1. System Requirements of the Store Owner/Web Developer
  • Any text or HTML editor.

  • The ability install and execute custom Perl CGI scripts on your server.

  • In order to ensure that transactions are secure, your server must also be a secure server.
2. System Requirements of the Customer
  • Since uShop consists of a series of Java applets and JavaScripts, the only requirement levied on the customer is that the customer must have a browser that supports Java and Java Scripts, such as Netscape 4.x, Internet Explorer 4.x or AOL.

    Mac IE Users should see here: http://www.uburst.com/uShop/macs.html

4. Steps In Creating An Online Store With uShopTM
Creation of an online store with uShopTM consists of the following steps:

  1. Setting up your directory structure on your development computer.
  2. Creating your store's HTML pages and adding any number of uShop Input Applets to the pages as the means by which customers can add items to the shopping cart.
  3. Transferring store pages and class files to your server.
  4. Creating/customizing your store's order forms.
  5. Installing the uShopTM Perl CGI scripts on your server.
  6. Using the Control Panel to configure Tax, Shipping, and other General Settings.
  7. Testing your online store.
Each of these steps is described in detail in the following sections of this User's Guide.



5. Setting Up Directory Structure
Because uShopTM is Java-based and because various browsers on various operating systems handle caching Java Applets differently, there is a specific directory structure that should be used in order to maximize browser compatibility. This recommended directory structure is based on years of experience in dealing with Java and the various browser differences and is illustrated in the figure below.



Figure 5.1 Recommended Directory Structure


As shown in figure 5.1, you should make a "classes" subdirectory in your main store directory. In this "classes" directory you should put ALL of the ".class" files that came with uShopTM, along with the several other image and html files that were originally located in the "classes" directory that was created when you unzipped/installed uShopTM on your local computer. This way, any HTML pages located in any of the "html" directories can refer to the items in the classes directory via the relative codebase "../classes/". (The codebase will be discussed further in the next section.)

Note: You can make as many "html" directories for your store as you like, however, it is important that they are all on the same directory level. That is, put all "html" directories on the same directory level as your "classes" directory.

So to sum up what you need to do to create the necessary directory structure for your store, on your development computer:

  1. Create your main store directory. You can actually call this directory anything you want - but we will refer to it as your "store" directory.


  2. Create a directory called "classes" as a subdirectory of your main store directory. Initially, you should copy all of the files from the "classes" directory that was created when you installed uShopTM on your local computer. So initially, in that "classes" directory, you should have the following files:

    • Approximately 45 .class files
    • index.html
    • template_cart.html
    • display_cart.html
    • template_product.html
    • display_product.html
    • demo_order_button.gif
    • example_order_button.gif
    • example_image_button.gif
    • example_discount.gif
    • ushop_logo.gif

    You may not actually need all of these files, but initially they should all be put in this directory.


  3. Create at least one "html" subdirectory. This is the main html directory that will be linked to when the customer wants to begin the interactive shopping experience. Again note that you can actually call this directory anything you want - but we will just refer to it as your "html" directory.


  4. Create an "images" directory as a subdirectory of your main store directory. This directory will be used as a common directory for image files. It is not required, but will make referring to/referencing images easier.




6. Setting Up Store Pages/Applets
Upon setting up your directory structure on your local computer, you can begin creating your store's product pages. This process simply involves using any text or HTML editor to create your product pages. The pages should be standard HTML pages (located in any of your "html" directories) that describe your products, display images of your products, and may utilize any additional multimedia capabilities/plug-ins that are supported by the browsers you intend to support. Again because of uShop's flexibility, these pages can have any layout/style that you want.

In addition to putting product descriptions on your store's HTML pages, you will also need to have a way to allow customers to select items that they want to purchase and add them to their virtual shopping cart. This is done via the use of uShop's Input Applets and Input JavaScripts. The uShopTM Input Applets and JavaScripts are described in the following two sections.


6.1 Input Applets
uShopTM comes with a variety of Input Applets that can be used to "Add" or "Input" items into the shopping cart. These applets have been designed to plug easily onto any web page, thus giving you almost total creative freedom when designing your web pages. That is, you can put any product descriptions, images and/or sounds on your pages - using regular HTML - and then add any of the various uShopTM Input Applets onto the pages as the means for adding the items to the shopping cart.

The uShopTM applets are added to your HTML pages via the standard <APPLET> HTML tags and configured via some easy-to-use parameters. The figure below shows an example applet and the HTML used to create the applet.



Figure 6.1.1 Example Applet and HTML


uShopTM comes with a large variety of Input Applets for handling various options, prices, and more! Check out the uShopTM Applet Reference for a complete list of all of the applets included with uShopTM as well as complete descriptions and examples of each of the applets.

Note: If you have never used Java applets before and/or would like to see how to utilize the uShopTM applets, it is recommended that you try the uShopTM Tutorial.

Need To Create Your Own Custom Input Applets?

In order to further increase uShop's flexibility, we have released the Java API for the uShopTM Input Applets. This allows you to create your own custom Input Applets. See the uShopTM Programmer's Guide for more information about creating your own custom Input Applets.

An Important Note About The "codebase" Parameter

When adding the uShopTM applets to your store pages, you must use the special "codebase" parameter to specify where the Java "class" files are located. As was shown in Figure 6.1.1 above, the "codebase" parameter is specified on the same line as the <APPLET> tag. The value of this parameter should be the relative path to your "classes" directory and must be set to the exact same value for all of your uShopTM applets. So in other words, just remember to set the codebase of ALL of your applets to codebase="../classes/".

Note: For more information about the codebase setting, see our codebase reference page at: http://www.uburst.com/uShop/codebase.html


6.2 JavaScripts
uShopTM has also provided a special JavaScript Interface Applet and an "Add Product" API (Application Program Interface) that allows you to create your own JavaScripts to interface with uShopTM. Like the uShopTM Input Applets, the JavaScripts can plug onto any web page. Observe the example in the figure below.



Figure 6.2.1 Example Input JavaScript


Note in this example that the quantity entry box and the "Add To Cart" button are just standard HTML <FORM> components. In fact, all components of this example are standard HTML and JavaScript components - with the exception of the call to the "addProduct()" function. The addProduct() function provides the means to add an item to uShop's shopping cart. This means that you can create any custom HTML/JavaScripts that you want and interface them with uShopTM by calling the addProduct() function. The parameters of the addProduct() function include the Product's ID, Name, Description, Weight, Quantity, Individual Price, Any Special Price Modifiers, the Classification, Any Shipping Modifier, and an indication of whether the product is Taxable or not. See the uShopTM Programmer's Guide for a complete description of these parameters as well as other special uShopTM JavaScript functions.

One Important Note to remember about using any of uShop's JavaScript functions/API, is that you must add the special uShopTM JavaScript Interface Applet to any page that will be using the JavaScript API. This uShopJSI applet is a special JavaScript Interface Applet that provides the means by which JavaScripts can call Java functions. Only one instance of this applet needs to be added to each page that will be using the uShopTM JavaScript API, And typically, the applet is added at the very bottom of the page (just before the closing </BODY> tag) with a WIDTH of 2 and HEIGHT of 2 ... to make it virtually invisible. The HTML to add this applet to your pages is shown in the figure below.



Figure 6.2.2 Example HTML For The JavaScript Interface Applet


Five JavaScript Input Examples have been included in the uShopTM Applet Reference. See the uShopTM Programmer's Guide for more information about creating your own custom JavaScripts to interface with uShopTM.


7. Special Applets
In addition to the various Input Applets that were described in the previous section, uShopTM also provides a variety of other applets that can be used for displaying the contents of the shopping cart, configuring general store preferences, performing searches, offering discounts, and initiating the order process. A brief overview of these applets is provided in the following sections.

For a complete description of all of uShop's applets, see the uShopTM Applet Reference.


7.1 Shopping Cart Applets
The uShopCart applets provide the means by which you can allow customers to view/modify the current contents of their virtual shopping cart. uShopTM currently has three different "Cart" applets that provide options ranging from showing the full details of each item that has been added to the shopping cart - down to an option to just show the current quantity, subtotal, or total of items in the shopping cart.

When setting up your online store, it is recommended that you create at least one HTML page that can be used as a "View Cart" page. On this page, you should put a large version of the uShopCart1 applet so that customers can go to this page at anytime to view the full details of the items currently in his/her virtual shopping cart.

If using a "FRAMES" layout for your online store, you may also want to put a smaller version of the cart - perhaps the uShopCart2 applet - in one of the frames. This way, customers can immediately see items get added to their shopping cart when they press the product's "Add" button.

See the uShopTM Demonstration Store for a working example of a main "View Cart" page and a working example of a small cart applet in a navigation frame.

To find out more about the uShopCart applets and their parameters, see the uShopTM Applet Reference.


7.1.1 Shopping Cart Template
In addition to the shopping cart applets described above, there is another shopping cart page that gets displayed once the customer chooses to begin the order process. This additional shopping cart page basically consists of an HTML formatted display of the shopping cart and some instructions to go back and make changes to the order or to continue with the order process. In order to make this page blend with the rest of your store's pages/style, we made a template for this page that you can customize. The template page is called "template_cart.html" and is located in the "classes" directory that was created when you installed/unzipped uShopTM on your local development computer. Feel free to modify the "template_cart.html" file to satisfy your preferences. To assist, a table describing the 3 available keywords has been provided below.


  Keyword Description
1 <USHOP INSTRUCTIONS> This keyword will be replaced at runtime with the continue page instructions as specified by the uShopOrderButton "instructions" parameter.
2 <USHOP CART> This keyword will be replaced by the HTML version of the shopping cart.
3 <USHOP BUTTONS> This keyword will be replaced by the BACK and CONTINUE buttons as specified by the uShopOrderButton "back_button" and "continue_button" parameters.

Table 7.1.1 Shopping Cart Template Keywords


7.2 Initialize Applet
The uShopInitialize applet provides the means by which you can change some of the default store settings such as the codebase, the currency symbol, some of the language specific-settings, and whether or not to display the Euro Totals.

If using this applet, remember that it's settings will not take effect until the visitor has viewed a page with this initialization applet on it. For this reason, it should be placed on one of your store's main entrance pages so that the settings will be applied as soon as possible. If using a "FRAMES" layout for your store, then you can also just put this applet in one of your smaller navigation frames...also ensuring that the applet will be viewed and the settings take effect.

To find out more about the parameters of the uShopInitialize applet, see the uShopTM Applet Reference.


7.3 Search/Browse Applets
As an alternative to adding all of your store products to static HTML pages, uShop provides several "search" and "browse" applets that read the product information from flat-text files and then dynamically generate the product pages. For complete descriptions of these applets and their parameters, see the uShopTM Applet Reference. For specific examples of how each applet is intended to be used, see uShopSearch1, uShopSearch2, uShopBrowse1 and uShopBrowse2.

The sections below focus on describing the format of the data files used by these applets and on how to create templates for the product pages that are dynamically generated by these applets.


7.3.1 Format Of Data Files
The data files used by the uShopSearch and uShopBrowse applets are standard bar-delimited text files. Each product in the file is listed on a separate line and each line in the file is separated into 15 bar-delimited fields. The table below describes each of the 15 fields associated with each product in the file.


  Field Description
1 ID The product's ID. Can be any combination of letters/numbers.
2 Name The product's Name. Can be any text string.
3 Full Description A full description of the product. This description will be displayed on the dynamically generated product page. It can be a text string of any length and may contain any number of HTML tags. Note: Do NOT include any bar (|) characters in this description since the bar (|) is a special character that is used as the field delimiter in the file.
4 Brief Description A brief description of the product. This brief description will be used when the item has been added to the shopping cart. It can be any text string, but is usually under 50 characters. You should not use any HTML tags in this parameter.
5 Option 1 The first set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
6 Option 2 The second set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
7 Option 3 The third set of options for the product - if any. The options must be comma-delimited and may contain price modifiers as described in the reference for the option parameter. If the product does not have any options, then leave this field blank.
8 Weight The weight of one unit of the item.
9 Quantity The default quantity of the item.
10 Price The price of the product. The price may be specified as a specific value or as a price table as described in the reference for the price parameter.
11 Classification The classification of the product. This field may be left blank or used in correlation with a price table as described in the reference for the price parameter.
12 Shipping Modifier Any shipping charge modifier associated with the product.
13 Taxable An indication of whether the product is taxable or not. If the product is taxable, set this field to "YES". Otherwise, set this field to "NO".
14 Keywords A list of keywords that may be used to identify the product in searches. Can be any number of keywords, each separated by a comma.
15 Image The name of the image that is associated with the product. Note that you do not need to specify the directory path of the images, since that is specified by the "search" or "browse" applet's "image_directory" parameter. Note that if the product does not have an image, then leave this field blank.

Table 7.3.1 Product Data File Fields


To see an example data file, Click Here.


7.3.2 Product HTML Template
The format of the product pages that are dynamically generated by the uShopTM "search" and "browse" applets is controlled by the "template_product.html" file (located in the "classes" directory). This file is nothing more than a standard HTML file with some special keywords used to indicate where the product fields will be inserted. Feel free to modify the "template_product.html" file to satisfy your preferences. To assist, a table describing the 6 keywords has been provided below.


  Keyword Description
1 UCATALOG_ID This keyword will be replaced by the product's ID.
2 UCATALOG_NAME This keyword will be replaced by the product's Name.
3 UCATALOG_DESCRIPTION This keyword will be replaced by the product's full description.
4 UCATALOG_PRICE This keyword will be replaced by the product's price.
5 UCATALOG_IMAGE This keyword will be replaced by the product's image.
6 UCATALOG_APPLET This keyword will be replaced by the product's input applet.

Table 7.3.2 Product Template Keywords


7.4 Discount Applets
uShopTM offers a variety of discount options via a built-in Coupon Manager, various quantity/price applet parameter settings, and the uShopDiscount applets. The uShopDiscount1 applet provides the means by which you can offer discounts based on the customer's subtotal, such as: "Save 10% on orders of $100 or more!". The uShopDiscount2 applet provides the means by which you can offer discounts across an entire product category/classification, such as "Save 10% on all Music CDs and 15% on all DVDs".

Similar to the uShopInitialize applet, the discount settings will not take effect until the visitor has viewed a page with one of the uShopDiscount applets on it. This means you may want to put your discount applet on the main entrance page to your store - or if you want to limit the discount to specific customers, perhaps put it on a "Members Only" page.

To find out more about the parameters of the uShopDiscount applets, see the uShopTM Applet Reference.

Also, be sure to check out the "Example Discount 1" JavaScript example in the uShopTM Applet Reference. It allows you to write your own custom discount calculations.

And of course, don't forget about uShop's Coupon Manager feature as an alternate way to offer/control discounts from the uShopTM Control Panel. The Coupon Manager will be discussed further below.


7.5 Order Button Applets
The uShopOrderButton applets (uShopOrderButton and uShopOrderButton2) are used to provide the means by which customers can initiate the order process. In addition, they also allow you to configure some order process preferences such as the location of your ushop.pl script, some of order process button labels and instructions, and some general shopping cart preferences.

It is recommended that one of these applets (a.k.a. "Order Button Applets") be placed on a "Place Order" page - possibly with instructions on how the order process works. As an example, see the "Place Order" page in the uShopTM Demonstration Store.

To find out more about the parameters of the uShopOrderButton applets, see the uShopTM Applet Reference.


8. Transferring Store Pages and Class Files To Server
Upon completion of creating your store pages on your local development computer, use your FTP program to transfer your entire store directory structure onto your server. This includes making a "classes" directory, "images" directory, and any "html" directories that you created while developing your store pages. Note that when transferring the uShopTM class files from your local computer to the "classes" directory on your server, it is important that you transfer the class files in "BINARY" or "RAW" transfer mode - NOT "ASCII" or "TEXT" transfer mode. Failure to transfer class files in "BINARY" or "RAW" transfer mode will result in such errors as "Bad magic number error" or "illegal constant pool error".

Upon transferring the files to your server, you should then be able to go to your website and successfully see your store pages just as they looked/functioned when on your local computer. In the next couple sections, you will complete your online store setup by configuring your store's order process/pages.


9. Creating and Customizing The Order Forms
uShopTM provides the ability for you to design your own custom order forms. This basically entails creating a few standard HTML forms with some pre-defined field names. The following 4 sections describe how to create your own custom order form for collecting billing/shipping information, your own custom order form for collecting credit card information, your own custom order form for collecting electronic checking information, and if desired, your own custom order form for collecting banking information.


9.1 Order Form Template
The order_template.html file (which is located in the "cgi" directory that was created when you installed/unzipped uShopTM on your local computer) is the main template for your store's order form. It should contain a form for collecting the customer's billing information, shipping information, comments, coupons, and any other general information that you want to collect from the customer. The payment information will be collected by the credit card and electronic check templates discussed in the next two sections.

When designing/customizing this "order_template.html" file, you can make your order form look however you like and contain any fields that you like via the use of standard HTML form syntax....and by giving the fields in the form some predefined field names. The table below contains a complete list of the predefined order form field names. For each of the fields in the table, there is also an indication of the type of <FORM> element each field can be - such as a "text" form element, a "textarea" form element, or a "selection" form element. Note that all of the fields in the table do not have to be used on your order form - just use the one's you want.


  Predefined Field Name Valid Form Element Types
1 billing_first_name text
2 billing_last_name text
3 billing_company text,select
4 billing_customer_id text,select
5 billing_street1 text,textarea
6 billing_street2 text,textarea
7 billing_city text
8 billing_state text,select
9 billing_zip_code text
10 billing_country text,select
11 billing_phone text
12 billing_fax text
13 billing_email text
14 billing_url text
15 billing_extra1 text,textarea,select
16 billing_extra2 text,textarea,select
17 billing_extra3 text,textarea,select
18 billing_extra4 text,textarea,select
19 billing_extra5 text,textarea,select
20 shipping_first_name text
21 shipping_last_name text
22 shipping_company text,select
23 shipping_customer_id text,select
24 shipping_street1 text,textarea
25 shipping_street2 text,textarea
26 shipping_city text
27 shipping_state text,select
28 shipping_zip_code text
29 shipping_country text,select
30 shipping_phone text
31 shipping_fax text
32 shipping_email text
33 shipping_url text
34 shipping_extra1 text,textarea,select
35 shipping_extra2 text,textarea,select
36 shipping_extra3 text,textarea,select
37 shipping_extra4 text,textarea,select
38 shipping_extra5 text,textarea,select
39 comments text,textarea
40 coupon_number text
41 extra_field1 text,textarea,select
42 extra_field2 text,textarea,select
43 extra_field3 text,textarea,select
44 extra_field4 text,textarea,select
45 extra_field5 text,textarea,select

Table 9.1.1 Order Form Field Names/Types


In addition to creating a <FORM> with the field names listed in Table 9.1.1 there are also a few special tags that you must add to your order form page. These special tags are listed/described in the table below. NOTE: These special tags are CASE SENSITIVE.


  Special Tag Description
1 <USHOP INSTRUCTIONS> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the "order", "review", and "print" instructions that are configured via the uShopTM Control Panel (Under the General Settings). You should add this special <USHOP INSTRUCTIONS> tag somewhere on your order template (typically centered at the top).
2 <USHOP FOOTER> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the navigation buttons and the shopping cart data. You must add this special <USHOP FOOTER> tag somewhere on your order template (typically centered at the bottom).
3 <USHOP TAX MENU> This optional case sensitive tag (with the < and > signs around it) will be replaced during runtime by the tax menu that is configured via the uShopTM Control Panel (Under General Settings). It is only necessary if you want to have a menu on your order form that asks the customer to select their tax rate...possibly with a note such as "For orders sent to Florida, please select the tax rate for that area.".
4 <USHOP SHIPPING MENU> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by a shipping selection menu that is created based on the shipping options that you configure via the uShopTM Control Panel (Under General Settings).

Table 9.1.2 Special Order Form Tags


Additional Notes About The Order Form Template

  • "extra" fields added to the order form must be used in the order in which they are listed at the top of the order_template.html.


  • If you want to make any of the fields on your order form "required" fields (ie. fields that must be filled in by the user), that can be done so via the uShopTM Control Panel (Under General Settings).


  • See the "order_template.html" file that was included with uShopTM as an example of how to create an order form.

9.2 Credit Card Template
The creditcard_template.html file (which is located in the "cgi" directory that was created when you installed/unzipped uShopTM on your local computer) is the template for your store's credit card payment form. It should consist of a form for accepting the customer's credit card payment information such as the card type, number and expiration date.

Like the "order_template.html" file, you can make your credit card order form look however you like and contain any fields that you like via the use of standard HTML form syntax....and by giving the fields in the form some predefined field names. The table below contains a complete list of these predefined credit card order form field names. For each of the fields in the table, there is also an indication of the type of <FORM> element each field can be - such as a "text" form element, a "textarea" form element, or a "selection" form element. Note that all of the fields in the table do not have to be used (such as the Issue Number) - just use the one's you want.


  Predefined Field Name Valid Form Element Types
1 cc_type text,select
2 cc_name_on_card text
3 cc_number text
4 cc_expiration text,select
5 cc_issue text

Table 9.2.1 Credit Card Payment Form Field Names/Types


In addition to creating a <FORM> with the field names listed in Table 9.2.1 there are also a couple special case sensitive tags that you must add to your credit card payment page. These special case sensitive tags are listed/described in the table below.


  Special Tag Description
1 <USHOP INSTRUCTIONS> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the credit card order instructions (as configured via the uShopTM Control Panel). You should add this special <USHOP INSTRUCTIONS> tag somewhere on your template (typically centered at the top).
2 <USHOP FOOTER> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the navigation buttons. You must add this special <USHOP FOOTER> tag somewhere on your template (typically centered at the bottom).

Table 9.2.2 Special Credit Card Payment Form Tags



9.3 Electronic Check Template
The echeck_template.html file (which is located in the "cgi" directory that was created when you installed/unzipped uShopTM on your local computer) is the template for your store's electronic check payment form. It should consist of a form for accepting electronic check payment information such as the bank name, check number, etc.

Like the "order_template.html" file, you can make your electronic check order form look however you like and contain any fields that you like via the use of standard HTML form syntax....and by giving the fields in the form some predefined field names. The table below contains a complete list of these predefined electronic check order form field names. For each of the fields in the table, there is also an indication of the type of <FORM> element each field can be - such as a "text" form element, a "textarea" form element, or a "selection" form element. Note that all of the fields in the table do not have to be used - just use the one's you want.


  Predefined Field Name Valid Form Element Types
1 echeck_bank_name text
2 echeck_bank_address text,textarea
3 echeck_name_on_check text
4 echeck_check_number text
5 echeck_account_number text
6 echeck_routing_number text
7 echeck_transit_code text

Table 9.3.1 Electronic Check Payment Form Field Names/Types


In addition to creating a <FORM> with the field names listed in Table 9.3.1 there are also a couple special case sensitive tags that you must add to your electronic check payment page. These special case sensitive tags are listed/described in the table below.


  Special Tag Description
1 <USHOP INSTRUCTIONS> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the electronic check order instructions (as configured via the uShopTM Control Panel). You should add this special <USHOP INSTRUCTIONS> tag somewhere on your template (typically centered at the top).
2 <USHOP FOOTER> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the navigation buttons. You must add this special <USHOP FOOTER> tag somewhere on your template (typically centered at the bottom).

Table 9.3.2 Special Electronic Check Payment Form Tags



9.4 Bank Template (German Version Only)
German Version Only: The bank_template.html file (which is located in the "cgi" directory that was created when you installed/unzipped uShopTM on your local computer) is the template for your store's bank transaction payment form. It should consist of a form for accepting bank transaction payment information such as the bank name, account owner, etc.

Like the "order_template.html" file, you can make your bank order form look however you like and contain any fields that you like via the use of standard HTML form syntax....and by giving the fields in the form some predefined field names. The table below contains a complete list of these predefined bank order form field names. For each of the fields in the table, there is also an indication of the type of <FORM> element each field can be - such as a "text" form element, a "textarea" form element, or a "selection" form element. Note that all of the fields in the table do not have to be used - just use the one's you want.


  Predefined Field Name Valid Form Element Types
1 bank_name text
2 bank_account_owner text
3 bank_account_number text
4 bank_code text

Table 9.4.1 Bank Payment Form Field Names/Types


In addition to creating a <FORM> with the field names listed in Table 9.4.1 there are also a couple special case sensitive tags that you must add to your bank payment page. These special case sensitive tags are listed/described in the table below.


  Special Tag Description
1 <USHOP INSTRUCTIONS> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the bank payment order instructions (as configured via the uShopTM Control Panel). You should add this special <USHOP INSTRUCTIONS> tag somewhere on your template (typically centered at the top).
2 <USHOP FOOTER> This special case sensitive tag (with the < and > signs around it) will be replaced during runtime by the navigation buttons. You must add this special <USHOP FOOTER> tag somewhere on your template (typically centered at the bottom).

Table 9.4.2 Special Bank Payment Form Tags



10. Configuring/Installing The uShopTM CGI Script
In addition to the large collection of Java Applets and JavaScripts, uShopTM consists of 3 Perl scripts/files that create the control panel and manage the order process. These scripts/files are:

  1. ushop.pl - The main script that gets executed whenever an order is placed and whenever the storeowner logs in to the uShopTM Control Panel.


  2. ushop-lib.pl - A library file that contains various subroutines used by the main ushop.pl script.


  3. ushop-languages.pl - Another library file that contains all of the language-specific text/translations use by the international versions of uShopTM.
The following sections describe how to install these uShopTM scripts on your server.

Note: Throughout these setup instructions, it will be assumed that your cgi directory is called "cgi-bin", however, on some servers it may actually be called "cgi-local" or simply, "cgi". Just substitute in whatever name applies on your server.


10.1 Familiarization With Installing and Executing Perl Scripts
If you've never installed or executed any Perl scripts on your server before, it is recommended that you first try installing our basic test script as described on the following reference page:

testscript.html

This simple Perl script is the most basic of Perl scripts and should help you to understand how to install and execute scripts on your server. It also will verify that your web hosting account is configured properly to run Perl scripts and will make installing the uShopTM scripts that much easier.


10.2 Creating A Data Directory On Your Server
Whenever an order is placed, uShopTM will create an order file in a data directory on your secure server. So use your FTP program to create a directory called "data" on your secure server. This "data" directory should be a subdirectory of your cgi-bin directory. Also, this directory will need to have write and execute permissions, so use your FTP program to set the permissions on this directory to WRITE and EXECUTE (chmod 733). Note that if you have an NT Server, you may have to get your Web Hosting Provider to give this new data directory permission to allow CGI scripts to WRITE to that directory.

See Section 4 on our uShop Security page for more information about correctly setting up the data directory.

Special Note For People Upgrading From uShop 2.0 - This "data" directory is equivalent to the "orders" directory that you used in previous releases. So you may just want to call this directory "orders" instead of "data". Just be sure you specify whatever name you are using for this directory in Question #5 of the script configuration questions.

After this step, your cgi-bin directory should have a new subdirectory called "data" and this "data" directory should have WRITE and EXECUTE permission.


10.3 Installing Order Templates On Your Server
While you're FTPed to your server, let's go ahead and transfer your order template files to your data directory. That is, transfer the following three (or four) files into your new data directory on your server:
  1. order_template.html

  2. creditcard_template.html

  3. echeck_template.html

  4. bank_template.html (German version only)
Note that these are the same four template files that were discussed above in Section 9. If you have not got around to customizing them for your store yet, then just go ahead and transfer the default template files that were included the "cgi" directory that was created when you installed/unzipped uShopTM on your local computer.

After this step, your "data" directory should have the following three (or four) files: order_template.html, creditcard_template.html, echeck_template.html, and bank_template.html.


10.4 Checking The File Extension Of The uShop Scripts
Currently, the uShopTM scripts are named ushop.pl, ushop-lib.pl, and ushop-languages.pl. Some servers, however, require that Perl (or any CGI scripts) have the extension .cgi instead of .pl. If this is the case for your server, simple rename the files using the .cgi extension so that the files are named ushop.cgi, ushop-lib.cgi, and ushop-languages.cgi, respectively. Note that if your server does support CGI scripts that end in ".pl" (as most servers do), then you can skip this step.


10.5 Configuring The Main uShop Script
At the top of the ushop.pl script, there are 13 configuration questions relating to how your server/website is configured. Follow the steps below to configure these questions for your server:

  • FIRST STEP: Open the "ushop.pl" file with any text editor (such as Note Pad or Word Pad).


  • Question #1: What is the path to Perl? As the very first line of the script, specify the path to Perl on your server. This will be something like #!/usr/bin/perl or #!/usr/sbin/perl on UNIX servers or #!C:/perl/perl.exe on NT servers. If you do not know your path to Perl, ask your web hosting provider. Note: Be sure to include the #! before the path.


  • Question #2: What is your uShop License Number? For this question, fill in the license number that you were given when you purchased uShop. If you are using the trial version, then simply set this parameter to:

    $license_number = "TRIAL VERSION";


  • Question #3: What is the URL of your website? For this question, simply fill in the URL of your store's website. For example:

    $store_url = "http://www.mystore.com";


  • Question #4: What is the secure URL of this script? For this question, enter what the secure URL of your ushop.pl script will be. Considering that you will be installing the ushop.pl script into the cgi-bin directory on your secure server, an example value is:

    $secure_script_url = "https://www.mystore.com/cgi-bin/ushop.pl";

    Note that if you do not have a secure server that can be accessed via https yet, then for now you can just use your public server here .... Just realize that transactions will not be secure until you get a secure certificate.


  • Question #5: What is the full or relative path to your data directory? For this question, you should enter the full or relative path from your cgi-bin directory to the "data" directory that you created in Section 9.2 above. For example, if you made the "data" directory as a subdirectory of your cgi-bin, you should be able to set this value to:

    $data_directory = "./data/";

    IMPORTANT NOTE: This $data_directory must be a path - NOT a URL (ie. It should NOT start with "http").

    Special Note For People Upgrading From uShop 2.0 - This "data" directory is equivalent to the "orders" directory that you used in previous releases. So you may just want to call this directory "orders" instead of "data".


  • Question #6: What is the name of the settings file? For Advanced Users Only! Most users will NOT need to change this setting, therefore, you can skip this question.


  • Question #7: What email method do you want to use? (SENDMAIL, BLAT or SOCKETS) For this question, specify the email method that the uShop script will use on your server. Available choices are "SENDMAIL", "BLAT", or "SOCKETS". SENDMAIL is recommended for all UNIX servers. "BLAT" is only available on NT servers. And "SOCKETS" can be used on both UNIX and NT servers. If you not know what email method to use, you may want to check with your Web Hosting Provider on what the recommended email method is for CGI scripts on your server. Assuming you have a UNIX server, an example value is:

    $email_method = "SENDMAIL";


  • Question #8: If using SENDMAIL in question #7 above, what is the path to sendmail? For this question, specify the path of sendmail on your server. This information can usually be found in your Web Hosting Provider's "CGI Help Page". Otherwise, just ask your provider what the path of sendmail is. An example value is:

    $sendmail_path = "/usr/lib/sendmail";

    NOTE: If you are not using SENDMAIL to send email, then you can just skip this question.


  • Question #9: If using BLAT in question #7 above, what is the path to Blat? For this question, specify the path of Blat on your server. This information can usually be found on your Web Hosting Provider's "CGI Help Page". Otherwise, just ask your provider what the path of Blat is. An example value is:

    $blat_path = "C:/Blat/blat.exe";

    NOTE: If you are not using BLAT to send email, then you can just skip this question.


  • Question #10: If using SOCKETS in question #7 above, what is the IP address (or name) of your mail server? For this question, specify either the IP address or the name of your mail server. An example value is:

    $smtp_address = "mail.mystore.com";

    or

    $smtp_address = "123.456.789.5";

    NOTE: If you are not using SOCKETS to send email, then you can just skip this question.


  • Question #11: What is the name of the uShop language file? Do not modify this setting unless you had to change the extension of your ushop-languages.pl file. That is, if you had to change the extension of the ushop-languages.pl file from ".pl" to ".cgi", then be sure to change the name here too:

    require "ushop-languages.cgi";

    NOTE: Most people will NOT need to change this setting and can therefore skip this question.


  • Question #12: What is the name of the uShop library file? Do not modify this setting unless you had to change the extension of your ushop-lib.pl file. That is, if you had to change the extension of the ushop-lib.pl file from ".pl" to ".cgi", then be sure to change the name here too:

    require "ushop-lib.cgi";

    NOTE: Most people will NOT need to change this setting and can therefore skip this question.


  • Question #13: What password would you like to use to login? For this question, specify any password that you would like to use when logging in to uShop's Control Panel. You can use almost any combination of letters and numbers for the password. An example value is:

    $login_password = "mypassword";


  • Question #14. (FOR AUTHORIZE.NET USER'S ONLY) What is your Authorize.Net Hash Key? If you plan on using Authorize.Net's payment gateway, you must configure a unique "fingerprint" or "transaction hash key" that Authorize.Net will use to validate requests from your store. Follow the instructions for configuring a transaction key, then enter your Authorize.Net-generated key as the answer to this question.

    $x_hash_key = "1234567890123456";


  • LAST STEP: After configuring all 14 questions as described above, save the ushop.pl script (as regular text if your editor asks) and exit your editor.
10.6 Transferring The uShop Scripts To Your Server
Once the uShop scripts have been configured as described in the previous sections, you can now transfer the scripts to your server. Use your FTP program to transfer all three scripts (ushop.pl, ushop-lib.pl, and ushop-languages.pl) PLUS the SimHMAC.pm perl module to the cgi-bin directory on your server. IMPORTANT NOTE: When transferring these files, be sure to transfer them in ASCII or TEXT mode - NOT BINARY or RAW mode.


10.7 Give The uShop Scripts READ and EXECUTE Permission
Once the uShop scripts have been transferred to your server, you must give the scripts READ and EXECUTE permission. Use your FTP program to give each of the scripts plus the SimHMAC.pm perl module READ and EXECUTE permission (chmod 755). Note that if you have an NT Server, you may have to get your Web Hosting Provider to give these scripts EXECUTE permission.


10.8 Testing The uShop Scripts
You can now test your scripts by using your browser to go to the URL of the ushop.pl script on your server. (This should be the same URL that you configured in Question #4 of the script setup questions). Upon going to this URL, you should get the uShop Login Screen similar to when you go to the URL of the script on our site:

https://www.uburst.com/cgi-bin/ushop/ushop.pl

If you encounter any errors or have any other trouble configuring the script, refer to the troubleshooting section on our online reference site:

http://www.uburst.com/uShop/reference.html

The next section describes how upon logging in, you can use the uShopTM Control Panel to configure your store's tax rates, shipping calculations and other general settings. It also describes the other elements of the uShopTM Control Panel such as the Coupon Manager, Affiliate Tracking System, Order Reader, and built-in Diagnostics.



11. The uShop Control Panel
Upon installing the uShop CGI Scripts, you can "Login" to the uShopTM Control Panel by going to the URL of the script on your server and using the password that you configured in the previous section as your "login_password". The uShopTM Control Panel provides the means by which you can configure your store's general settings (tax, shipping, etc.), create/delete coupons, operate an affiliate tracking system, securely read orders, and generate diagnostic reports. Each of these features is described in detail in the following sections.


11.1 General Settings
The "General Settings" button on the main control panel creates a sub-menu by which you can configure the order form preferences, payment options, tax and shipping options, email notices, and various other general settings.


11.1.1 Store Information
The "Store Information" button creates a form by which you can specify your store's Name, Address, Phone, Fax, and URL. Press "Apply" to apply the settings.


11.1.2 Order Form
The "Order Form" button creates a form by which you can specify the name of your order template files, and the instructions that will appear on the "Order" page and the "Review Order" page. It also provides a list of all of the pre-defined field names that may have been used in your order template file....and the means by which to make any of the fields "Required Fields".

Note that "template 1" refers to the first page of the order process (the page in which the customer enters his/her billing/shipping information). "template 2" refers to the second page of the order process (also known as the "Review Order" page). "template 3" refers to the template used for the final receipt page of the order process. Typically you will use the same template for all three pages, but just in case you want to change them....this is where you can do so.

Required Fields

To make a field required, simply type in the name of the field next to the corresponding pre-defined field name. For example, if you wanted to make the customer's billing phone number required, then simply enter the words "Phone Number" next to the "billing_phone" field. Or as another example, suppose you added an extra element on your order form for the "extra_field1" field name and you were using it to collect the customer's favorite color. To make that extra field required, you would simply type in the text "Favorite Color" next to the "extra_field1" field. Note that whatever text you enter next to the fields that are required is what the message will display if the customer does not fill in that field. For instance, if you put "Hello World" next to the "billing_first_name" field, the customer will get a message saying "Please fill in your Hello World" if he/she leaves the "billing_first_name" field on the order form blank.


11.1.3 Payment Options
The "Payment Options" button creates a form by which you can specify the payment options that your store will accept. Each of the available options are described below.

Credit Card Payment Option

These fields relate to whether or not you will be accepting credit card payments for manual processing. This is not to be confused with credit card payments that will be processed by automated systems such as Authorize.Net, Planet Payment, LinkPoint or PayPal - those options are specified below.

Electronic Check Payment Option

These fields relate to whether or not you will be accepting electronic check payments for manual processing. This is not to be confused with electronic check payments that will be processed by automated systems such as Authorize.Net, Planet Payment, LinkPoint or PayPal - those options are specified below.

Bank Payment Option

These fields relate to whether or not you will be accepting bank transaction payments for manual processing. (German version only).

Print Payment Option

These fields relate to whether or not you will be offering a "Print" payment option. A Print Payment Option can be useful to provide a form that can be easily printed out and then used for phone, fax, or mail orders.

'Contact Me' Option

These fields relate to whether or not you will be offering a "Contact Me" option. A 'Contact Me' option can be useful to provide a way for customers to inquire about specific items without actually purchasing them yet.

COD Payment Option

These fields relate to whether or not you will be offering a COD (Cash On Delivery) payment option.

Authorize.Net Payment Option

These fields relate to whether or not you will be using Authorize.Net to handle processing your credit card and/or electronic check orders.

Special Instructions for Configuring Authorize.Net (March 2003)

Configure Authorize.Net:
  1. Log in to your Authorize.Net Control Panel
  2. Under "Settings", select "Obtain Transaction Key". Record the generated transaction key for use later.
  3. Make sure the URL of your uShop CGI script is listed under Settings | Response/Receipt URLS.
  4. Make sure the URL of your uShop CGI script is also listed under Settings | Relay Response
  5. Change your Authorize.Net account to "Password Only" mode. (Settings | Password Required Mode)
  6. Under "Settings", disable the WebLink method if it is currently enabled. (Note: This option won't even show up in the settings if you already have WebLink disabled, or if you are a new Authorize.Net merchant.)
Configure uShop:
  1. BE SURE THAT YOU HAVE SPECIFIED THE TRANSACTION KEY that you recorded from Authorize.Net in the ushop.pl script "Configuration Question #14".
  2. Log in to your uShop Control Panel
  3. Choose General Settings-->Payment Options
  4. Under the Authorize.Net Payment option on uShop, make sure that the Authorize.Net URL is current: https://secure.authorize.net/gateway/transact.dll (as of March 2003)
  5. Specify your Authorize.Net Login ID - this is the same ID that you would use to log in to Authorize.Net's virtual terminal
  6. Choose Test Mode while you place some test orders; switch to "Live Mode" when you are finished testing


Planet Payment Option

These fields relate to whether or not you will be using Planet Payment to handle processing your credit card and/or electronic check orders.

LinkPoint Payment Option

These fields relate to whether or not you will be using LinkPoint or YourPay to handle processing your credit card and/or electronic check orders. See the reference page at
LinkPoint - http://www.uburst.com/uShop/linkpoint.html
YourPay - http://www.uburst.com/uShop/yourpay.html
for assistance configuring the uShop LinkPoint or YourPay Interface.

*PayPal Payment Option (*requires additional purchase to use this interface)

These fields relate to whether or not you will be using PayPal to handle processing your credit card and/or electronic check orders.

Suggested values for configuring the "PayPal" payment option:

PayPal Payment Option: Yes
Payment Selection Button Label: PayPal
Payment Select Button Image: NONE
Payment Selection Instructions: Click here to pay by PayPal.
PayPal Account:
PayPal Invoice Label: Payment for invoice number:
PayPal URL: https://www.paypal.com/cgi-bin/webscr
Thank You Message: Thank you! Your order has been placed.


Custom Payment Option

For Advanced User's Only! These fields relate to whether or not you will be using a custom payment processing system to handle processing your credit card and/or electronic check orders.


Note:For the latest information on uShop's Interfaces to Payment Processing Systems, visit http://www.uburst.com/uShop/interfaces.html


11.1.4 Taxes and Shipping
The "Taxes & Shipping" button creates a form by which you can setup your store's tax rates, shipping options, and handling fees. Each of these settings are described below:

Tax Settings

These fields allow you to setup various tax options for your store. The following table describes each tax field.

Parameter Description
Default Tax Rate The default tax rate. Valid values are "0.0%", "6.0%", etc. (Be sure to specify the % sign).

As an example, suppose you wanted to charge all customers a tax rate of 7.0%. To do this, just set this value to "7.0%".

Often, this Default Tax Rate parameter will be used in correlation with one or more of the tax table parameters below. The default value is "0.0%".
Tax Table (States) This parameter allows you to automatically assign a specific tax rate based on what state the customer lives. The format of this parameter is STATE=TAXRATE, where STATE is the state and TAXRATE is the tax rate that will be assigned to customers from that state. You can specify as many STATE=TAXRATE combinations as you like, just be sure to separate each combination with a comma.

As an example, suppose you wanted to automatically charge customers in Florida a tax rate of 6.0% and customers in Texas a tax rate of 7.0%. You would then set this parameter to "FL=6.0%,FLORIDA=6.0%,TX=7.0%,TEXAS=7.0%". (All other customers will be charged the default tax rate.)

Leave this field blank if not used.
Tax Table (Countries) This parameter allows you to automatically assign a specific tax rate based on what country the customer lives. The format of this parameter is COUNTRY=TAXRATE, where COUNTRY is the country and TAXRATE is the tax rate that will be assigned to customers from that country. You can specify as many COUNTRY=TAXRATE combinations as you like, just be sure to separate each combination with a comma.

As an example, suppose you wanted to automatically charge customers in France a tax rate of 16.0% and customers in Germany a tax rate of 18.0%. You would then set this parameter to "FRANCE=16.0%,GERMANY=18.0%". (All other customers will be charged the default tax rate.)

Leave this field blank if not used.
Tax Menu Rates If you are using a tax selection menu to have customers select the tax rate for their area (which is useful for states that have multiple tax rates), this parameter allows you to specify the tax rates that will appear in the tax selection menu.

As an example, suppose you wanted the tax selection menu to give customers the choice of "0.0%" tax or "6.0%" tax or "7.0%" tax, then you would set this parameter to "0.0%,6.0%,7.0%".

Usually this parameter would be used in correlation with the "Tax Menu Table" parameter below.

Leave this field blank if not used.
Tax Menu Table This parameter allows you to specify specific states and/or countries that don't go by the default tax rate. Typically this parameter would be used by in correlation with a Tax Menu Rates parameter described above.

As an example, suppose you want to charge a default tax rate of "0.0%" for everyone except for customers from Florida. To do this, you would set the "Default Tax Rate" (see above) to "0.0%" and you would set this "Tax Menu Table" parameter to "FL,FLORIDA". On your order form, you could put a note that "Customers from Florida must select the tax rate for their area." This "Tax Menu Table" parameter would then make sure that customers from "FL" or "FLORIDA" select a tax rate other than the "Default Tax Rate".

Leave this field blank if not used.
Tax Shipping Charge This parameter allows you to specify whether or not to tax the shipping charge. Set this value to "YES" if you want the shipping charge taxed. Otherwise, set this value to "NO".
Base Tax On This parameter allows you to specify whether tax will be based on the customer billing address or shipping address. Set this value to "Shipping Address" if you want the tax determined based on where the order is being shipped. Otherwise, set this value to "Billing Address" if you want the tax to always be based on the customer's billing address.

Table 11.1.4.1 Tax Rate Settings


SPECIAL TIP: Some storeowners like to manually include the tax in the prices of each product... so that they can say that "Tax has been included in the price of the product." For those storeowners, we added an option to specify that tax is inclusive... so that tax is not re-added when calculating the final total amount of the order. To mark tax as being inclusive, open the "ushop-lib.pl" file and locate the following line near the top of that script:

$tax_inclusive = "NO";

Change that line to:

$tax_inclusive = "YES";


Shipping Methods

The Shipping Method fields allow you to configure up to 5 different shipping options for your store. For each of these shipping options, you can specify the Calculation Type, Name, and Value of the shipping method. The following table describes the various Shipping Calculation Types that are available for each of your Shipping Options.


Shipping Calculation Type Description
Flat Fee The "Flat Fee" shipping calculation type allows you to setup the shipping charge as a flat fee. To charge a flat fee, simply set the value parameter to the fee that you want to charge. For example, if you want to create a shipping option that charges a flat fee of $5.00, then you can set the fields for that shipping option as:

CALCULATION TYPE: Flat Fee
SHIPPING NAME: My Shipping Method
SHIPPING TABLE/VALUE: $5.00

Or as another example, if you want shipping to be free, then you can set the fields for a shipping option as:

CALCULATION TYPE: Flat Fee
SHIPPING NAME: My Free Shipping Method
SHIPPING TABLE/VALUE: $0.00

Note that in all cases, the "SHIPPING NAME" field can be any text you want such as "UPS", "FED EX", or "My Shipping Method".
Weight Table The "Weight Table" shipping calculation type allows you to setup the shipping charge to be based on a weight table. The weight table should be specified as a series of weight=charge combinations - each separated by a comma - and with the first weight in the table being 0. This is best illustrated with an example:

Suppose you want to setup the following weight table: 
WEIGHT            SHIPPING CHARGE
0 - 9.999         $5.00
10 - 19.999       $6.00
20 - 29.999       $7.00
30 and over       $9.00
To do this, you would set the shipping fields to:

CALCULATION TYPE: Weight Table
SHIPPING NAME: My Shipping Method
SHIPPING TABLE/VALUE: 0=$5.00,10=$6.00,20=$7.00,30=$9.00
Weight Formula The "Weight Formula" shipping calculation type allows you to setup the shipping charge to be based on the formula:

Shipping Charge = (ORDER WEIGHT * X) + Y

So as an example, suppose you wanted to charge $5.00 for the first pound and $1.00 for each additional pound. You could then set shipping fields to:

CALCULATION TYPE: Weight Formula
SHIPPING NAME: My Shipping Method
SHIPPING TABLE/VALUE: $1.00,$4.00

Where the VALUE indicates X=$1.00 and Y=$4.00.

Note: You do NOT have to use "pounds" as your store's weight unit. You can actually use any weight unit you want - providing you keep it consistent. That is, if you want your store to go by kilograms for instance, then just be sure that all weights in your store are given in kilograms.
Subtotal Table The "Subtotal Table" shipping calculation type allows you to setup the shipping charge to be based on a subtotal table. The subtotal table should be specified as a series of subtotal=charge combinations - each separated by a comma - and with the first subtotal in the table being 0. This is best illustrated with an example:

Suppose you want to setup the following subtotal table: 
SUBTOTAL          SHIPPING CHARGE
$0 - $49.99       $10.00
$50 - $99.99      $8.00
$100 - $199.99    $5.00
$200 and over     $0.00
To do this, you would set the shipping fields to:

CALCULATION TYPE: Subtotal Table
SHIPPING NAME: My Shipping Method
SHIPPING TABLE/VALUE: $0=$10.00,$50=$8.00,$100=$5.00,$200=$0.00
Subtot