uShop Online Shopping System

Last Update: March 1, 2004
Version 3.6

Table Of Contents
1. Introduction	Section 1
2. Features	Section 2
3. System Requirements	Section 3
4. Steps In Creating An Online Store With uShop^TM	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

uShop^TM 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!

uShop^TM 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 uShop^TM, the only limitation is your imagination!

2. Features

Features of uShop^TM 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 uShop^TM.

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 uShop^TM it yours! Note that an additional license must be purchased for each additional store that you setup using uShop^TM.

And much, much more!

3. System Requirements

The system requirements of uShop^TM 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 uShop^TM

Creation of an online store with uShop^TM consists of the following steps:

Setting up your directory structure on your development computer.
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.
Transferring store pages and class files to your server.
Creating/customizing your store's order forms.
Installing the uShop^TM Perl CGI scripts on your server.
Using the Control Panel to configure Tax, Shipping, and other General Settings.
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 uShop^TM 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 uShop^TM, along with the several other image and html files that were originally located in the "classes" directory that was created when you unzipped/installed uShop^TM 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:

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

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 uShop^TM 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.

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.

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 uShop^TM Input Applets and JavaScripts are described in the following two sections.

6.1 Input Applets

uShop^TM 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 uShop^TM Input Applets onto the pages as the means for adding the items to the shopping cart.

The uShop^TM 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

uShop^TM comes with a large variety of Input Applets for handling various options, prices, and more! Check out the uShop^TM Applet Reference for a complete list of all of the applets included with uShop^TM 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 uShop^TM applets, it is recommended that you try the uShop^TM 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 uShop^TM Input Applets. This allows you to create your own custom Input Applets. See the uShop^TM Programmer's Guide for more information about creating your own custom Input Applets.

An Important Note About The "codebase" Parameter

When adding the uShop^TM 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 uShop^TM 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

uShop^TM 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 uShop^TM. Like the uShop^TM 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 uShop^TM 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 uShop^TM Programmer's Guide for a complete description of these parameters as well as other special uShop^TM JavaScript functions.

One Important Note to remember about using any of uShop's JavaScript functions/API, is that you must add the special uShop^TM 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 uShop^TM 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 uShop^TM Applet Reference. See the uShop^TM Programmer's Guide for more information about creating your own custom JavaScripts to interface with uShop^TM.

7. Special Applets

In addition to the various Input Applets that were described in the previous section, uShop^TM 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 uShop^TM 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. uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM "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

uShop^TM 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 uShop^TM Applet Reference.

Also, be sure to check out the "Example Discount 1" JavaScript example in the uShop^TM 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 uShop^TM 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 uShop^TM Demonstration Store.

To find out more about the parameters of the uShopOrderButton applets, see the uShop^TM 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 uShop^TM 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

uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM Control Panel (Under General Settings).

See the "order_template.html" file that was included with uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM 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 uShop^TM CGI Script

In addition to the large collection of Java Applets and JavaScripts, uShop^TM consists of 3 Perl scripts/files that create the control panel and manage the order process. These scripts/files are:

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

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

ushop-languages.pl - Another library file that contains all of the language-specific text/translations use by the international versions of uShop^TM.

The following sections describe how to install these uShop^TM 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 uShop^TM scripts that much easier.

10.2 Creating A Data Directory On Your Server

Whenever an order is placed, uShop^TM 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:

order_template.html

creditcard_template.html

echeck_template.html

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 uShop^TM 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 uShop^TM 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 uShop^TM Control Panel to configure your store's tax rates, shipping calculations and other general settings. It also describes the other elements of the uShop^TM 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 uShop^TM 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 uShop^TM 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:

Log in to your Authorize.Net Control Panel
Under "Settings", select "Obtain Transaction Key". Record the generated transaction key for use later.
Make sure the URL of your uShop CGI script is listed under Settings | Response/Receipt URLS.
Make sure the URL of your uShop CGI script is also listed under Settings | Relay Response
Change your Authorize.Net account to "Password Only" mode. (Settings | Password Required Mode)
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:

BE SURE THAT YOU HAVE SPECIFIED THE TRANSACTION KEY that you recorded from Authorize.Net in the ushop.pl script "Configuration Question #14".
Log in to your uShop Control Panel
Choose General Settings-->Payment Options
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)
Specify your Authorize.Net Login ID - this is the same ID that you would use to log in to Authorize.Net's virtual terminal
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
Subtotal Formula	The "Subtotal Formula" shipping calculation type allows you to setup the shipping charge to be based on the formula: Shipping Charge = (ORDER SUBTOTAL * X) + Y So as an example, suppose you wanted to charge $1.00 on the first dollar and 2-cents ($0.02) on each dollar after that. You could then set shipping fields to: CALCULATION TYPE: Subtotal Formula SHIPPING NAME: My Shipping Method SHIPPING TABLE/VALUE: $0.02,$0.98 Where the VALUE indicates X=$0.02 and Y=$0.98.
Quantity Table	The "Quantity Table" shipping calculation type allows you to setup the shipping charge to be based on a quantity table. The quantity table should be specified as a series of quantity=charge combinations - each separated by a comma - and with the first quantity in the table being 0. This is best illustrated with an example: Suppose you want to setup the following quantity table: QUANTITY SHIPPING CHARGE 1 - 4 $6.00 5 - 9 $8.00 10 - 19 $10.00 20 and over $15.00 To do this, you would set the shipping fields to: CALCULATION TYPE: Quantity Table SHIPPING NAME: My Shipping Method SHIPPING TABLE/VALUE: 0=$6.00,5=$8.00,10=$10.00,20=$15.00
Quantity Formula	The "Quantity Formula" shipping calculation type allows you to setup the shipping charge to be based on the formula: Shipping Charge = (TOTAL QUANTITY * X) + Y So as an example, suppose you wanted to charge $3.00 on the first item and 50-cents ($0.50) on each item after that. You could then set shipping fields to: CALCULATION TYPE: Quantity Formula SHIPPING NAME: My Shipping Method SHIPPING TABLE/VALUE: $0.50,$2.50 Where the VALUE indicates X=$0.50 and Y=$2.50.
Custom	For Advanced User's Only! The "Custom" shipping calculation type allows you to program your own custom shipping method/calculation. See the uShop^TM Programmer's Guide for more information about programming your own custom shipping calculation.
Not Used	Indicates that the shipping option is not used.

Table 11.1.4.2 Shipping Calculation Types

Handling Settings

The Handling Settings fields allow you to configure your store's handling fees (if any). The following table describes each handling field.

Parameter	Description
Default Handling Fee	This parameter allows you to specify the default handling fee that all customers will be charged. The format of this parameter is simply the fee that you want to charge such as "$5.00" or "$2.00". As an example, suppose you wanted to charge all customers a handling fee of $1.00. To do this, just set this parameter to "$1.00". Often this parameter will be used in correlation with one of the handling table parameters below. The default value for this parameter is "$0.00".
Handling Table (States)	This parameter allows you to specify specific handling fees for customers from specific states. The format of this parameter is STATE=HANDLINGFEE, where STATE is the state and HANDLINGFEE is the handling fee that will be charged to customers from that state. You can specify as many STATE=HANDLINGFEE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to charge customers in California a handling fee of $2.00 and customers in New York a handling fee of $3.00. You would then set this parameter to "CA=$2.00,CALIFORNIA=$2.00,NY=$3.00,NEW YORK=$3.00". (All other customers will be charged the Default Handling Fee.) Leave this field blank if not used.
Handling Table (Countries)	This parameter allows you to specify specific handling fees for customers from specific countries. The format of this parameter is COUNTRY=HANDLINGFEE, where COUNTRY is the country and HANDLINGFEE is the handling fee that will be charged to customers from that country. You can specify as many COUNTRY=HANDLINGFEE combinations as you like, just be sure to separate each combination with a comma. As an example, suppose you wanted to charge customers in Canada a handling fee of $2.00 and customers in England a handling fee of $3.00. You would then set this parameter to "CANADA=$2.00,ENGLAND=$3.00". (All other customers will be charged the Default Handling Fee.) Leave this field blank if not used.

Table 11.1.4.3 Handling Fee Settings

11.1.5 Email Notifications

The "Email Notifications" button creates a form by which you can specify some options related to email notifications and email receipts. The following table describes each of these fields/options.

Parameter	Description
Primary Email	This required parameter allows you to specify the main email address to which order notification emails will be sent. That is, this is the email address that will receive the email notification whenever an order is placed. It is also the email address that will appear as the "FROM" email address on email receipts sent to customers.
Secondary Email(s)	This parameter allows you to specify additional email addresses (if any) to which order notifications will also be sent. That is, in this field you can list any additional email addresses - each separated by a comma - to which a copy of all order notifications will be sent. Note that these email addresses will NOT appear on the customer's receipt emails...only the PRIMARY email address (configured above) will appear on customer receipt emails. Leave this field blank if not used.
Store Subject	This parameter allows you to specify the "Subject" that will appear on all email notifications sent to the storeowner. An example subject might be "Order Notification".
Email Customer	This parameter allows you to specify whether or not an email receipt will be sent to the customer. Set this parameter to "YES" if you want an email receipt sent to the customer (whatever email address that the customer enters in the "billing_email" field on the order form). Otherwise, set this parameter to "NO".
Customer Subject	This parameter allows you to specify the "Subject" that will appear on email receipts that are sent to the customer (if any). An example subject might be "Order Receipt".
Email Message	This parameter allows you to specify an additional message that will be included on email receipts. This message can be any text such as "Thank you for your order. Upon approval of your payment information, your order will be shipped in 3-5 days." Leave this field blank if not used.
Wrap Description	On all email receipts and notifications, the product information will be arranged in several columns...similar to the shopping cart. That is, column 1 will contain the Product ID, column 2 will contain the Product Name and Description, column 3 will contain the Product Quantity, and column 4 will contain the Product Price. Some products, however, may have large descriptions that don't fit within it's fixed column width. This "Wrap Description" parameter allows you to specify whether or not to "Wrap" long descriptions to the next line or not. Set this field to "YES" if you want long product descriptions to be wrapped around onto additional lines. Otherwise, set this field to "NO" in order to truncate long descriptions onto one line. (Note that the uShop Order Reader will always allow you to get the full description....so you may not find it necessary to always have the full description in the email notifications).
ID Column Width	On all email receipts and notifications, the product information will be arranged in several columns...similar to the shopping cart. That is, column 1 will contain the Product ID, column 2 will contain the Product Name and Description, column 3 will contain the Product Quantity, and column 4 will contain the Product Price. This parameter allows you to specify the number of characters that will be used for the ID column. The default value is "10" characters, however, if your products have longer IDs, you may want to increase this field accordingly. Note that if you don't want the ID to be displayed on the receipt at all, then set this parameter to "0".
Description Column Width	On all email receipts and notifications, the product information will be arranged in several columns...similar to the shopping cart. That is, column 1 will contain the Product ID, column 2 will contain the Product Name and Description, column 3 will contain the Product Quantity, and column 4 will contain the Product Price. This parameter allows you to specify the number of characters that will be used for the NAME/DESCRIPTION column. The default value is "40" characters, however, if your products have longer Names and Descriptions, you may want to increase this field accordingly. Note that the "Wrap Description" option above can be set to "YES" in order to wrap long product names and descriptions onto additional lines. Note that if you don't want the NAME/DESCRIPTION to be displayed on the receipt at all, then set this parameter to "0".
Quantity Column Width	On all email receipts and notifications, the product information will be arranged in several columns...similar to the shopping cart. That is, column 1 will contain the Product ID, column 2 will contain the Product Name and Description, column 3 will contain the Product Quantity, and column 4 will contain the Product Price. This parameter allows you to specify the number of characters that will be used for the QUANTITY column. The default value is "10" characters, however, if you expect very large or small quantities to be selected, then you may want to adjust this field accordingly. Note that if you don't want the QUANTITY to be displayed on the receipt at all, then set this parameter to "0".
Price Column Width	On all email receipts and notifications, the product information will be arranged in several columns...similar to the shopping cart. That is, column 1 will contain the Product ID, column 2 will contain the Product Name and Description, column 3 will contain the Product Quantity, and column 4 will contain the Product Price. This parameter allows you to specify the number of characters that will be used for the PRICE column. The default value is "10" characters, however, if your products have very large or small prices, then you may want to adjust this field accordingly. Note that if you don't want the PRICE to be displayed on the receipt at all, then set this parameter to "0".

Table 11.1.5.1 Email Notification Settings

11.1.6 Miscellaneous Settings

The "Miscellaneous" button creates a form by which you can specify some miscellaneous store settings such as logging and receipt page options. The following table describes each of these fields/options.

Parameter	Description
Referral Page Validation	As an added measure of security, this parameter allows you to specify whether or not a check is performed on whether all POSTs to your store come from your website. That is, by setting this field to "YES", a check will be performed to ensure that any posts to your store actually came from your website. It is recommended that during development, you leave this field set to "NO" so that you can test your store pages from your local desktop computer. Once you have tested your store pages and transferred them to your server, it is recommended that this field be set to "YES".
Maintain Customer Log	This parameter allows you to specify whether or not to maintain a customer data log. If this field is set to "YES", then the following information will be written to a "ushop-customers.log" file on your server: Order Number Order Date Subtotal Total Billing Last Name Billing First Name Billing Company Name Billing Customer ID Billing Street Address Billing City Billing State Billing Zip Billing Country Billing Phone Billing Fax Billing Email Billing URL Note that the format of the "ushop-customers.log" file is a bar-delimited text file with each of the above fields.
Maintain Inventory Log	This parameter allows you to specify whether or not to maintain an inventory log. If this field is set to "YES", then for each item that is ordered, the following information will be written to a "ushop-inventory.log" file on your server: Order Number Order Date Product ID Product Name Product Quantity Product Price Note that the format of the "ushop-inventory.log" file is a bar-delimited text file with each of the above fields.
Thank You Page	As an alternative to the displaying the standard "Thank You" page after an order is placed, this parameter allows you to specify the URL (beginning with "http" or "https") of a custom "Thank You" page that will be displayed after an order is placed. Leave this field blank if not used.
Receipt Page Footer HTML	This parameter allows you to specify any custom HTML that will be displayed in the FOOTER portion of the "Thank You" page that is generated after an order is placed. External Affiliate Tracking Option Many external affiliate tracking systems require that you add specify HTML on the bottom your "Thank You" page with some special parameters such as the order ID and the subtotal. In order to aid in interfacing the uShop "Thank You" page with external affiliate tracking systems, we have provided several special USHOP TAGS that will be replaced at the time this "Receipt Page Footer HTML" is displayed. That is, you can use any of the following USHOP TAGS in this parameter's custom HTML: USHOP_SUBTOTAL - Will be replaced by the order's subtotal. USHOP_TOTAL - Will be replaced by the order's total. USHOP_ORDERID - Will be replaced by the order's unique order id. Leave this field blank if not used.
Order Reader Template	This parameter allows you to specify the name of the order template that is used by the uShop Order Reader. The default value is to use the same "order_template.html" file that is used during runtime (the same order page that is displayed when the customer is placing the order). If that page has additional banner ads and other graphics on it, however, the storeowner may not want to have those items on the order form that he/she prints out for their records. So this parameter can be used to specify an alternate order template file (created with the same rules/keywords as the main order template).

Table 11.1.6.1 Miscellaneous Settings

11.2 Coupon Manager

The "Coupon Manager" button on the main control panel creates a page with two forms on it. One form is for creating new coupons and the other is for deleting coupons.

11.2.1 Adding Coupons

The "Add Coupon" form provides the means by which you can create/offer new coupons. To create a new coupon, simply enter a unique coupon number, the value of the coupon, and the expiration date of the coupon and then press the "Add Coupon" button.

A few notes about coupons:

The Value of the coupon can be specified as either a "Percent Off" such as "10%" or "20%" or as a flat rate discount such as "$5.00" or "$10.00".

There is a way to specify the coupon number via banner ads and other links to your store. See the section on Linking Options below for more information.

There is no limit to the number of coupons that you can create.

The maximum expiration date at this time is 5 years from the current date.

11.2.2 Deleting Coupons

The "Delete Coupon" form provides a list of all of your current coupons. (Coupons that have expired will have an asterisk* next to them.) It also provides the means by which you can delete coupons. To delete a coupon, simply select the coupon that you want to delete and then press the "Delete Coupon" button.

11.3 Affiliate Tracking

The "Affiliate Tracking" button on the main control panel creates a sub-menu by which you can operate your own Affiliate Tracking System. Options of the Affiliate Tracking System include the ability to Add, Edit, and Delete affiliates, the ability to Edit and Clear the Affiliate Log, and the ability to generate reports on the affiliates.

For information about linking affiliates to your store, see Section 17 in this User's Guide and our online reference page about affiliate cookies at http://www.uburst.com/uShop/cookies.html.

11.3.1 Add Affiliate

The "Add Affiliate" button on the Affiliate Tracking Control Panel displays a form from which you can create an account for a new affiliate. Below is a description of each of the fields associated with creating a new affiliate account.

*Unique ID - This field allows you to specify a Unique Id for the new affiliate. The affiliate will use this ID when linking visitors to your store and will be the means by which orders can be associated with the affiliate. You can enter any single text string (number and letters - no spaces!) for this field. Example values are "A00001" or "REF00234".

*Full Name - This field allows you to specify the full name of the affiliate. You can enter any text for this field.

Company - If the affiliate is associated with a specific company, this field allows you to specify the company's name. You can enter any text for this field.

Address - This field allows to record the mailing address of the affiliate. Simply enter the address as you would like it to appear - using as many lines of text as you want.

Phone - This field allows you to specify the phone number of the affiliate.

Fax - This field allows you to specify the Fax number (if any) of the affiliate.

Email - This field allows you to specify the email address of the affiliate.

URL - This field allows you to specify the URL of the affiliate's website.

*Rate - This field allows you to specify the rate of commission for the affiliate. There are two available ways to setup the rate: either as a percentage of sales or as a flat rate per order. Each of these is described further below:

Percentage Of Sales

The Percentage Of Sales option allows you to give the affiliate commission based on a percentage of the sales that were referred through him/her. To do this, simply add a percent (%) to the value you enter in the "Rate" field. For instance, say you want to reward an affiliate by giving him/her 1.0% of the sales that he/she referred to your store. To do this, simply set the Rate parameter to "1.0%".

Flat Rate Per Order

The Flat Rate Per Order option allows you to give the affiliate commission based on a fixed rate per order that was referred through him/her. To do this, simply specify the amount per order in the "Rate" field. For instance, say you want to reward an affiliate by giving him/her $1.00 per order that resulted from a referral from him/her. To do this, simply set the Rate parameter to "$1.00".

Password - This field allows you to specify a unique password that the affiliate can use to login to check his/her current affiliate report.

11.3.2 Edit Affiliate

The "Edit Affiliate" button on the Affiliate Tracking Control Panel provides the means by which you can select and edit the account of an existing affiliate. You will first be prompted to select the affiliate that you want to edit and then will be presented with the Edit Affiliate form. The fields on this form are similar to those on the Add Affiliate form (described above) and will be pre-set to the current values of the affiliate.

11.3.3 Delete Affiliate

The "Delete Affiliate" button on the Affiliate Tracking Control Panel provides the means by which you can delete an entire account of an affiliate. You will first be prompted to select the affiliate that you want to delete and then prompted to confirm the deletion. Select "YES" to delete the affiliate or "NO" to abort the deletion.

11.3.4 Edit Affiliate Log

The "Edit Log" button on the Affiliate Tracking Control Panel provides the means by which you can edit the affiliate log for a specified order. Upon pressing the "Edit Log" button, you will be prompted to enter the Order ID (a.k.a. the Order Number) of the log entry that you want to edit. An Edit Affiliate Log form will then be created and will display the Order ID, Affiliate ID, Order Date, and Order Subtotal. Simply make any changes to this information and then press "Submit". Note: If you want to delete an entry entirely, set the Subtotal field to "$0.00" or leave it blank.

11.3.5 Clear Affiliate Log

The "Clear Log" button on the Affiliate Tracking Control Panel provides the means by which you can clear all entries in the affiliate log up to a specified date. Upon pressing the "Clear Log" button, you will be prompted to enter the date up to which all affiliate log entries will be cleared. The format of the date must be MM/DD/YY, where MM is a two-character month, DD is a two character day of month, and YY is the last two characters of the year (00 for 2000, 01 for 2001, 02 for 2002,... and so on.).

11.3.6 Affiliate Reports

The "Affiliate Reports" button on the Affiliate Tracking Control Panel provides the means by which you can generate an affiliate report on all affiliates or on a specified affiliate. Upon pressing the "Reports" button, you will be prompted to select a specific affiliate for which to generate the report or to just generate the report on ALL affiliates. The report will contain a summary of all orders that were referred by an affiliate since the last time the affiliate log was cleared.

11.4 Order Reader

The "Order Reader" button on the main control panel provides the means by which you can securely read and manage orders files. That is, whenever an order is placed, an order file is created on the server and an email notification of the order is sent to the storeowner notifying him/her of the new order. This email does NOT contain any of the customer's sensitive payment information because regular email is not necessarily secure. Instead, uShop^TM has provided this Order Reader to allow you to easily and securely read the entire order - including the payment information.

11.4.1 Reading Orders

The order reader form which is displayed when you press the "Read Order" button on the main control panel displays a time-ordered list of all of the order files that are currently on the server. To securely read an order file, simply select the order number and then press the "Read Order" button on the Order Reader form. The selected order file will then be displayed in its entirety - including the payment information - which is displayed at the very top of the order file.

11.4.2 Deleting Orders

As you receive more and more orders, the number of order files on your server will gradually increase. A "Total Order Files" indicator is provided in the upper left of the Order Reader form so that you can see the current number of order files on your server. At any time, you can choose to use the "Delete Order" button located on the Order Reader form to delete a specified order file. To delete an order file, simply select the Order Number of the file you want to delete and then press the "Delete Order" button. You will be prompted to confirm the deletion. Press "Yes" to confirm or "No" to abort the deletion.

11.5 Diagnostics

The "Diagnostics" button on the main control panel provides a means for checking out your current uShop^TM configuration. Upon pressing this button, uShop^TM will perform a series of tests to check such things as your directory structure, file permissions, and email configuration. It also will display all of your configured settings which may be needed when seeking support.

12. Testing Your Store

Throughout the development of your online store - and especially once your store is complete - it is very important to test it out. Try adding items to the cart and then try placing test orders. Check that your order form is functioning properly and that the tax, shipping, and handling calculations are performing as you expect. Also, be sure to check your store pages one on different browsers - as there are slight differences in the way different browsers display Java applets, make sure their appearance is acceptable on the various browsers that you intend to support.

If you run into any problems, refer to the troubleshooting section on our online reference site:

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

13. Troubleshooting

In order to keep the troubleshooting tips as up to date as possible, we have moved the troubleshooting section to our online reference site at:

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

14. Tax Examples

As described in the Section 11.1.4 above, uShop^TM can be configured to handle a variety of tax options. It even makes it possible to develop your own custom tax calculations (See the uShop^TM Programmer's Guide for information about programming your own custom tax calculations.) This section, however, describes how to setup a couple of the most common tax configurations.

Taxes In The United States

Typically in the United States, online stores are only required to charge taxes on orders that are shipped to the same state where the store is physically located. To complicate things, however, each state often has various tax rates based on where the customer is located within the state. So deal with this, it is recommended that on the order form, you add a "Tax Menu" from which customers in the storeowner's state must select the tax rate for the area that the order is being shipped. To do this:

Use the <USHOP TAX MENU> option as described above in Section 9.1 to add a tax menu to your order form. You may also want to put some note above the <USHOP TAX MENU> tag stating that "For orders sent to STATE, please select the tax rate for that area."....where STATE is the state in which the store is located.

The tax rates that are actually listed in the tax selection menu, can be configured via the "Tax Menu Rates" field - as described in Section 11.1.4 above. A typical setting might be "0.0%,6.0%,6.25%,6.5%,6.75%,7.0%,7.25%,7.5%"....where each of the available tax rates for the storeowner's state are listed. Note that it is important to have "0.0%" listed somewhere in the list so that orders that go anywhere else will not be charged tax.

You can configure uShop^TM to force all customers in the storeowner's state to select a value other than the default 0.0% tax rate, via the use of the "Tax Menu Table" field (Also described in Section 11.1.4). For the "Tax Menu Table" field, you should list the storeowner's state. For example, if the store is located in Florida and you want to force all orders sent to Florida to select a tax rate, then you would set the "Tax Menu Table" to "FL,FLORIDA".

Typical settings for the other tax fields listed in Section 11.1.4 are:

Default Tax Rate = "0.0%"
Tax Table (States) = ""
Tax Table (Countries) = ""
Tax Shipping Charge = "NO"
Base Tax On = "Shipping Address"

Taxes In Other Countries

Stores located in other countries typically do not need to charge tax unless the order is shipped to the same country as where the store is located. For example, suppose an online store is located in France and the store wishes to charge a tax rate of 16.5% for all orders shipped to France, but no tax on orders shipped to other countries. This could be automated via the following Tax parameter settings:

Default Tax Rate = "0.0%"
Tax Table (States) = ""
Tax Table (Countries) = "FRANCE=16.5%"
Tax Menu Rates = ""
Tax Menu Table = ""
Tax Shipping Charge = "YES"
Base Tax On = "Shipping Address"
SPECIAL TAX OPTION: 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";

15. Shipping Examples

The shipping examples have been moved up into Section 11.1.4 ....where all of the available shipping calculation types are discussed.

For additional shipping options, see the uShop^TM Programmer's Guide for information about programming your own custom shipping calculations.

16. Handling Examples

The handling examples have been moved up into Section 11.1.4 ....where all of the handling parameters are discussed.

For additional handling options, see the uShop^TM Programmer's Guide for information about programming your own custom handling calculations.

17. Linking Options

Because uShop^TM stores consist mostly of static HTML product pages, you can link customers virtually any page in your store. There are, however, a few additional linking options that may come in handy when affiliates link customers to your store and/or when you want to use banner ads to preset discount coupons. Both of these special linking options are described below.

For more information about linking affiliates and coupons to your store, see our online reference page about affiliate and coupon cookies at http://www.uburst.com/uShop/cookies.html.

17.1 Affiliate Linking

When using uShop's Affiliate Tracking System, affiliates should link customers to your store by linking them to the URL of the ushop.pl script on your server. For example, if the script is located on your server at http://www.mystore.com/cgi-bin/ushop.pl, then you should tell affiliates to link to your store by creating links to the following URL:

http://www.mystore.com/cgi-bin/ushop.pl?id=AI

Where the AI is the unique affiliate id that was assigned to the affiliate when he/she signed up to become an affililiate. This would then cause a cookie to be set (which would last for 1 week) so if the visitor who linked to the store via the above URL places an order, then the correct affiliate will get commission for the referral. Note that once the cookie is set, the visitor will be redirected to the store's main URL. If the affiliate wanted to redirect the visitor to a specific page in the store (or a different URL), then an additional "url" parameter can be specified in the link. For example, by adding "&url=http://www.mystore.com/hello.html" to the URL such as:

http://www.mystore.com/cgi-bin/ushop.pl?id=AI&url=http://www.mystore.com/hello.html

Not only will the cookie be set, but the visitor will also be redirected to the URL "http://www.mystore.com/hello.html".

For more information about affiliate cookies, see our online reference page about affiliate cookies at http://www.uburst.com/uShop/cookies.html.

Affiliate Reporting

Note also that affiliates can "login" to see their current affiliate report by linking to the URL of the script on your server....with the special "?command=report" syntax after it. For example, if the ushop.pl script is located on your server at https://www.mystore.com/cgi-bin/ushop.pl, then you can tell affiliates that they can view their affiliate report at any time by logging in at the following URL:

https://www.mystore.com/cgi-bin/ushop.pl?command=report

17.2 Coupon Linking

There may come a time where you want to setup a banner ad that says something like "Use This Coupon To Save 10% On All Purchases". But rather than making the visitor write down the coupon number before linking to your store, you may just want to have the banner ad automatically set a coupon cookie that will automatically insert the coupon number on the order form for the customer. To do this, just have the banner ad link customers to the URL of the ushop.pl script on your server and use the special "?coupon=CN" syntax to set a coupon cookie. For example, if the script is located on your server at http://www.mystore.com/cgi-bin/ushop.pl, then you should link to your store via the following URL:

http://www.mystore.com/cgi-bin/ushop.pl?coupon=CN

Where the CN is the coupon that you setup via the uShop^TM Coupon Manager. This would then cause a cookie to be set so that when the visitor goes to place an order, the coupon number will automatically be inserted on the order form. Note that once the cookie is set, the visitor will be redirected to the store's main URL. If you wanted to redirect the visitor to a specific page in the store (or a different URL) however, then an additional "url" parameter can be specified in the link. For example, by adding "&url=http://www.mystore.com/hello.html" to the URL such as:

http://www.mystore.com/cgi-bin/ushop.pl?coupon=CN&url=http://www.mystore.com/hello.html

Not only will the coupon cookie be set, but the visitor will also be redirected to the URL "http://www.mystore.com/hello.html".

For more information about coupon cookies, see our online reference page about affiliate/coupon cookies at http://www.uburst.com/uShop/cookies.html.

18. Internationalization

As of December 1, 2000, uShop 3.0 is available in the following languages: Danish, Dutch, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, and Swedish. In these international versions of uShop, all of the instructions are still in English, but all of the applet and control panel labels have been translated for use by our friends around the world.

See http://www.uburst.com/uShop/international.html

19. Creating Your Own Java Applets

In case you can't find the applet you need in the uShop^TM Applet Reference, we have released the Java API for the uShop^TM Input Applets. This allows you to create your own custom Input Applets. See the uShop^TM Programmer's Guide for more information about creating your own custom Input Applets.

20. Creating Your Own JavaScripts

To further increase uShop's flexibility, we have provided the means by which you can create your own JavaScripts to interface with uShop^TM. See the uShop^TM Programmer's Guide for more information about creating your own custom JavaScripts.

21. CD-ROM Catalogs

Because uShop^TM consists of Java Applets and JavaScripts which run locally on your browser and do not require any server interaction, not only can you put your store online, but you can also put your store on CD-ROM! See our website for more information about Interactive CD-ROM Cataloging Options (http://www.uburst.com/uShop/cds.html).

22. Other References

Additional references and resources can be found at:

The uShop^TM Applet Reference

The uShop^TM Programmer's Guide

The uShop^TM Tutorial

The uShop^TM Reference Site