Host by K Host by K ~ Home Page
  FAQ | Hosting Packages | Sign Up Now
Host by K Host by K ~ Rainbow Line
Online Manual ~ Table of Contents Merchant OrderForm v1.5 Documentation


<----Return to Manual

Click for printer friendly page

What do you want to order today?
  • Smart looking invoices to print, mail, or fax
  • Logging and/or emailing orders to Merchant
  • Logging to a RDB format for import to PC database
  • Customer email confirmation
  • Online Checking information input
  • Flexible configurations for discounts or handling charges
  • Adaptable shipping methods, rates, configurations
  • Automatic foreign shipping rate change
  • Multi State tax configurations with adjustable computations
  • Accepts input for Cards, Checks, custom OrderForms
  • Built in support for custom shipping configurations
  • Built in support for customizing additional field input
  • Built in switch to require "cyber permission" approval
Will I be able to install this program?

>>> GO TO TABLE OF CONTENTS

Merchant OrderFormv1.5 are program scripts written in Perl 5 code for use on Unix type or NT systems using CGI (Common Gateway Interface). The program scripts are installed and run on the server where your Web Site is.

You should be able to install the OrderForm page and the program's script files if:

  • You know how to edit a Web Page file (an HTML file) and transfer it to your server
  • You know how to FTP (file transfer Protocol) a regular text file to your server
The documentation can help someone with little to no experience installing CGI scripts; however, if you don't know the difference between an HTML file and a CGI file, then you're probably in for a rough ride. Begin with the Quick Start section and follow the instructions carefully.
How do I make it do this?

>>> GO TO TABLE OF CONTENTS

Merchant OrderFormv1.5 is loaded with settings and options, from simple to complex, that can be adjusted and/or configured to process your OrderForm input in many ways.

You can read an overview of each configuration section's abilities and limitations under the heading further on in this document:

Each of the configuration sections begins with an overview of what that group of settings can do. If you need to know if you can adjust things the way you need them, then find your way to the "What can these settings do" section for that group of configurations, and consult the summary there.

You can also find answers for other questions under the heading:

Table of Contents for this Documentation

Merchant OrderFormv1.5

What is Merchant OrderForm ?

>>> GO TO TABLE OF CONTENTS

Merchant Order Formv1.5 is a smart Online OrderForm and invoice system for small product collections. It interacts smartly with the user, and presents friendly feedback. It does not process credit card or online check transactions in real-time. It provides four ways to process orders from your Online Customers:

  • Send the order via email to the Merchant
  • Log the invoice and orders into a Master Logging file
  • Log the invoice and orders into a delimited file for RDM import
  • Send the Customer an email verification of their orders
It is convenient for small collections of products, since you only need to add new items to the HTML OrderForm input page. Once Merchant OrderForm is up and running on your Web site, then you only need to change your HTML OrderForm to update, add, or delete your line of products. It's as simple as editing your HTML OrderForm page.

You can layout your HTML OrderForm page using checkboxes, dropdown boxes, listboxes, radio buttons, or hidden input, and Merchant OrderForm will sort out your Customer's orders and present smart looking invoices.

Merchant Order Form v1.5 will handle as many New Products as your server has memory; however, this would not seem practical since the customer doesn't want to go through hundreds of checkboxes to order items. So, it's probably more applicable to smaller collections of products, whereas, a database / shopping cart system seems more user friendly for large product collections. A database / shopping cart system also allows the shopper to "add" products from any page on the Web Site, and collect in a "cart." Merchant OrderForm produces invoices from one OrderForm at a time.

Quick Start Instructions

>>> GO TO TABLE OF CONTENTS

You need to do two things to get the scripts up and running in test mode:

  • FTP the scripts to your server's Cgi-Bin exactly as they are
  • Set file permissions on each of the files so they will execute
The program files are already configured to run without any of the features enabled in the configuration file, for basic installation and testing. Once you have all 3 scripts running, then you can begin to play with the configurations and features in the configuration file, but I recommend getting all scripts running in basic mode first before you start to configure it for your site needs.
  • First, FTP (File Transfer Protocol) the 9 files below straight to your Unix, Linux server's CGI-BIN. They should transfer and run exactly as is, without even opening them up. Eventually you will need to open the configuration file, but you don't need to do that now. For now, just send them over as they are when you unpacked them.
Important: Make sure to FTP the files in ASCII mode only, do not use the FTP Binary Mode, else the scripts won't work on your server's end.
  • Next, you need to set correct file Permissions on the files you just sent to your server's CGI-BIN.
Note: Many FTP programs have a way to set Unix type permissions from their menus. If you don't have a way to set "permissions" from your FTP, then get one that can, it's easier than doing it by Telnet (if you even have Telnet access on your server). You can find some Freeware FTP Clients (programs) at the NoNags Web Site.
Setting correct file permissions

>>> GO TO TABLE OF CONTENTS

Here are the files you need to FTP and the corresponding permissions they need to work. Transfer all 9 files, and set the 4 "cgi" files with complete "execute" permissions, then set the 2 "dat" files and 3 "rdb" files with complete "execute" and "write" permissions.
 

Filename Owner Permissions Group Permissions Other Permissions
orderconfig.cgi Read, Write, Execute Read, Execute Read, Execute
orderfinal14.cgi Read, Write, Execute Read, Execute Read, Execute
orderform14.cgi Read, Write, Execute Read, Execute Read, Execute
ordercount14.cgi Read, Write, Execute Read, Execute Read, Execute
orderlog.dat Read, Write, Execute Read, Write, Execute Read, Write, Execute
ordernumber.dat Read, Write, Execute Read, Write, Execute Read, Write, Execute
ordermain.rdb Read, Write, Execute Read, Write, Execute Read, Write, Execute
ordercustom.rdb Read, Write, Execute Read, Write, Execute Read, Write, Execute
orderorders.rdb Read, Write, Execute Read, Write, Execute Read, Write, Execute
  • Note:If you are using a Telnet connection to set permissions in Unix then you can use:
  • directory/> chmod 755 filename.cgi for Read, Execute permissions
  • directory/> chmod 777 filename.cgi for Read, Write, Execute permissions
Now you should have the basic scripts and the configuration file set to run from your Web Browser.
Running the scripts in test mode

>>> GO TO TABLE OF CONTENTS Perform a test and see if you can run each of the scripts independently from your Web Browser. You don't need to submit anything from the HTML orderform to run them. Simply plug in the HTTP addresses where you placed the scripts on your server into your Web Browser's address or location bar. Here's an example from my site.

All three of the main script files should run this way. If they don't and you're sure you followed the two important rules above (1) FTP ASCII Mode only, and (2) Setting Permissions, then you are getting a server error for some reason. If you are getting server errors, you should consult the section of this documentation - A checklist for installing CGI on Unix type servers.

Of course, you'll get error messages when you run the first script <orderform14.cgi> saying you haven't completed the data entry fields, but the script is running, it's doing exactly what it's supposed to do without the information submitted by your OrderForm Page.

You'll also get incomplete information when you run the other two scripts this way <ordercount14.cgi> and <orderfinal14.cgi> because they aren't processing any relevant information, but the scripts should still run.

The <orderfinal14.cgi> file will not test this way if "cyber permission" is enabled. It is disabled in the download package. Unless you turned it on in the configuration file, then it should be disabled. Also, all other switches are initially turned off in the configuration file, disabling things like file locking, file logging, and mailing, which could prevent this final file from executing independently.

When you have tested all three main script files and they are running on your server, then you are ready to begin your journey of configuring Merchant OrderForm for your site needs. You can place your HTML input OrderForm file <orderform14.html> anywhere you want, and point the FORM POST tag to the first processing file <orderform14.cgi>

Here are some examples:

  • <FORM method=POST action="../cgi-bin/orderform14.cgi">
  • <FORM method=POST action="http://www.yourdomain.com/cgi-bin/orderform14.cgi">
  • <FORM method=POST action="https://www.yourdomain.com/cgi-bin/orderform14.cgi">
This type of HTML tag is embedded inside the HTML code of your HTML OrderForm input Page. It identifies an address and file name of where the contents of the FORM will be sent when someone clicks the "Submit" button on the OrderForm. You browser then sends the entire contents of any FORM input to the file you identified. In the above examples, all your FORM content is sent to the Merchant OrderForm first processing file, which takes over from there.
Setting Up Your OrderForm Input Page

>>> GO TO TABLE OF CONTENTS

There is a main example HTML OrderForm included in the package <orderform14.html>. It includes all the input fields that you might want to use for your OrderForm. There are also some samples of different ways you might want to make your OrderForm input page.

They are meant to serve as examples, and you can create your own HTML OrderForm if you want. You can also modify the example OrderForms any way you want for your site needs. If you create your own OrderForm then just make sure you use the same name / value pairs that I have used. A detailed listing of these name / value pairs can be found in Appendix 1 at the end of this documentation. The scripts process information by these names only. Therefore, your OrderForm input Page will have to use these same "input names."
 
Here are some ways you may want to customize your OrderForm input Page:

>>> GO TO TABLE OF CONTENTS

  • If you want to process only Online checking account information, then: Omit the credit card section on the OrderForm input page. You can place the "I'll pay by check" checkbox as a hidden variable. Now your form appears to process only checks.
  • You can also remove the "checking account" section altogether and the form appears to process only credit card transactions.
  • Remove the "additional customer information" section if you don't need this, but make sure to keep the phone number, fax number, and email fields if you need them, the "phone field" has a validation rule, you'll have to remove this if you don't use the phone field.
  • You can remove everything but shipping destination, and place the "pay by check" as a hidden variable, and the form appears to allow processing for money order only.
  • You can set up an OrderForm that builds a product, like a custom made computer, by creating sections with drop down menus. The customer selects each component by choosing it from the list.
  • You can set up an OrderForm where a set of radio buttons, checkboxes, or drop down boxes list options for color, size, etc for a product.
It's okay to omit fields that you don't need. Just leave them out of your OrderForm input Page. The scripts don't care about what is not there to process. However, the first processing script attempts to validate that necessary input is present. Necessary input is considered:
  • At least one ordered item, whether user chosen or hidden input
  • At least one choice of payment type, whether user chosen or hidden input
  • The essential shipping destination information
  • The "select" input for Country and State is best as drop down menus
  • And a phone number in case some Merchant contact is needed
If you need additional input other than the fields I have named in the main OrderForm input Page, then you can configure the scripts to process input names of your own. See the documentation on Working with settings in the configuration file - Installing Custom Fields. You can place an unlimited number of name / value pairs in your HTML input tags, as long as you tell the configuration file what their names are. Make sure you don't use any of the same name / value pairs that I've already assigned.  Consult the listing in Appendix 1.
What are those other files in the package ?

>>> GO TO TABLE OF CONTENTS

My examples of the HTML OrderForm input Pages also include links to picture windows to put images of your products in. You can take this out, and everything will work fine.

The <scripts.jpg> file is just a logo. When you configure the three processing files, you can use a similar image for your site logo, or you can omit the image and just use a name.

Adding products to the HTML OrderForm input Page.

>>> GO TO TABLE OF CONTENTS

Merchant Order Form v1.5 scripts will process the product items in your HTML OrderForm input Page as long as you keep to the format I've set up.

Here are the two rules:

  • The name must be exactly "order"
  • The value must contain four elements separated by 4 minus signs as delimiters
Here's the exact HTML syntax to add new checkboxes to your HTML OrderForm input Page.
<input type="checkbox"
name="order"
value="Item Name----Description of the Item----11.65----1">
This tag will create a new checkbox that, when checked by the user, will send the Item Name, Item Description, Price, and ShipCode to the CGI processing files. The processing files will identify only the "order" NAME for processing product data, and the VALUE data will be extracted correctly only if the delimiters are used correctly. You can use any input type you like as long as the name / value pair follows the pattern outlined. You can use radio buttons, drop down boxes, list boxes, check boxes. Just make sure you always name a product "order" and give the value the 4 elements defined. All of your product names will be "order." This is how the scripts tell it's a product to be sorted out separately from the other information. Usually, HTML Form input names would not be duplicated; however, you must duplicate them here.

You can also format the appearance of your checkboxes, dropdown boxes, listboxes, radio buttons anyway you want. The way they appear on the page, the type of labeling you use has nothing to do with the underlying input name / value tags. You can use images, links, or anything else to list and describe your products as long as the underlying input name / value attributes are correct.

If you get errors from the invoice processing you better check this portion very carefully and make sure that the NAME and VALUE delimiters are correct. The delimiter "----" 4 minus signs together with no spaces between text must be correct, and you must include all 4 pieces of information in correct sequence for the VALUE.

  • NAME="order"
  • VALUE="Item Name----Item Description----Price----ShipCode"
The Price must be in 2 decimal format "100.00" and it must be a raw number with no dollar signs or other formatting like commas, etc. If the price is fifty cents then you would show that as "0.50", or $1,275.35 would be shown as "1275.35". The ShipCode must be free of any formatting also, and can contain only a numerical value. For now, you can just put ones for your ShipCode. Merchant OrderForm v1.5 has some serious flexibility when computing shipping charges, and in order to fully appreciate what you can do with your ShipCodes you may have to read about shipping computations in the next section called - Working with settings in the configuration file.
How to think about using the ShipCodes:

>>> GO TO TABLE OF CONTENTS

You don't need to understand the configuration file in detail at this point, but you will need some forethought to how you want to assign ShipCode values to each product. So, I will cover some information on how to think about using the ShipCodes.

  • Using the Global Settings


>>> GO TO TABLE OF CONTENTS

There are two ways to think about using the global shipping schema:
Calculate shipping charges as percentage of price
The first way is to simply calculate shipping charges based on the cost of products. If you use this method then you don't need shipcodes, because you already have product prices listed. Just assign a "1" to every shipcode for this schema. The "1" won't be used under this schema, but you still need the value there as a placeholder. Shipping will be computed using the actual price of products.
Calculate shipping charges by weight per item, or dollar amount per item
The second way to use global settings is to set up your shipcodes as either a:
 
  • Weight per item or a
  • Shipping amount per item
Which are interchangeable. Then use the "Global Settings" (discussed in the next section) and compute shipping charges based on the overall weight or overall amount of the entire invoice.

Either this item would be 35 cents to ship, or it would weigh 0.35 pounds.

  • NAME="order" VALUE="Name----Description----12.95----0.35"
Note: If using the "Global Setting" schema use the weight or cost values for your entire list of products. Don't try to use weight for one and amount to ship for another. This is really a different schema, not the "Global" method. When using the "Global Settings" for shipping computations, then the entire invoice's orders are totaled with the [weight X quantity] for each product. You will instruct the configuration file to deal with the total weight or shipping amount from the invoice in different ways. Here are some of the ways the "Global" computations would work:

  • Using a rate per pound
  • Using a rate for every 2.5 pounds
  • Using a one time rate regardless of the totals
  • Using a rate for each 5 pounds up to a maximum of $ 25.00 then charges are free
  • Using the Individual Item Settings 


>>> GO TO TABLE OF CONTENTS

Don't even think about using these settings unless you are ready to think about multiple arrays in perl 5. This schema uses 12 individual settings for each shipcode assigned, and can get complicated. Better to start with the suggestions above, which should cover most shipping needs.

If you want to use this level of computations then, you would use a system of numbering for your ShipCodes starting at 1, and proceeding in sequence to how ever many different individual computations you need.

It might help to think of this schema in the same weights and amounts way, except that we won't be assigning weights and amounts in the HTML OrderForm input Page tags. Instead, we will be assigning a group number to each product, and in the configuration file we will assign the particular characteristics (amounts / weights) for that group.

In this schema, you create a more complex system of shipping rules, where individual sets of shipping rules will be applied to each ShipCode. This system must use sequential integers starting from one. If you plan to use this method, don't assign decimal numbers to the ShipCodes, else the script won't recognize the ShipCode. When these settings are enabled in the configuration file, the script looks only for ShipCodes 1, 2, 3, 4, etc.

Example: Let's say we have four different ShipCodes from 1 to 4 exactly. You can give any number of products a ShipCode of 1, thereby assigning it to the individual computation rules for group 1. Likewise for group 2, 3, and 4.

Note: You don't have to use all the groups you set up, but that would be rather silly, not to mention pointless. If you set up a 4 number system, and only use ShipCodes for 1, 3, and 4, in your line of products, well then, obviously, you only need to use a 3 number system. The script will work fine looking for any products with a ShipCode of "2" and seeing none, will go on to checking the other ShipCodes. In computing, the scripts will look for all the 1's, then all the 2's, etc., keeping a cumulative total for each ShipCode.

  • Writing your own code to process ShipCodes


>>> GO TO TABLE OF CONTENTS

This built in feature is enabled in the configuration file, and bypasses all other shipping computations. It's a way for someone to write their own code for processing shipping charges. If you're going to do this, then assign ShipCodes as you would in the "Individual Item Settings" above, in sequential integers starting at 1. Then when you write your code in the actual processing file, you write your own rules for computing each ShipCode group. There are more notes about this further on in the documentation at the section - Other Switch Functions.

Working with settings in the configuration file

>>> GO TO TABLE OF CONTENTS

Each of the configuration sections begins with an overview of what that group of settings can do. If you need to know if you can adjust things the way you need them, then find your way to the "What can these settings do" section for that group of configurations, and consult the summary.

Here are the major configuration sections that govern the behavior of the program:

Some basics before we get started.

>>> GO TO TABLE OF CONTENTS

Once your scripts are running in test mode, and you have set up your OrderForm input Page, then you are ready to configure the features and settings you want to use. Merchant OrderForm gets its instructions on what to do from the configuration file, so you'll be editing this file.

Important: Use an ASCII editor only, do not use a rich text, or fancy word processor to edit the files unless it lets you work in ASCII mode only. It's also best to use an ASCII editor that will store the file in Unix format, if you are working from a Windows machine. Two of the processing files are too large for the regular Windows Notepad. Therefore, you may have to find a good ASCII text editor.  Check out the NoNags Web Site.

Okay, I wish I knew of some encouragement here. The configuration file is almost five pages long printed. If you're not used to CGI installations or perl looking code, then I know it looks like a mess. The good news -- you don't have to read about the features you don't want to use. But, if you want to turn on a feature, or adjust a setting, then the best way to do that is to use this portion of the documentation as a reference. If you're pretty savvy about perl looking stuff, then jump right into the file and start setting stuff by using the comments embedded in the configuration file.

The file you'll be opening is called <orderconfig.cgi> and here's some points to know about cruising around this file:

  • Settings are grouped together under CPITALIZED HEADINGS
  • In perl, all comments start with the # character. So, when you see a line like this:
# this is a comment about something
You don't need to modify anything past the # character.
You're looking at notes and instructions.
  • When modifying a setting, be very careful to leave all the punctuation intact. Perl is not like HTML, and it is not forgiving if you leave one little single quote off, or one little semicolon. The perl interpreter won't compile the code if a syntax error exists.
  • Most settings are simply changing a number from zero to one or visa versa
    • Zero is Off
    • One is On
  • Other settings are text based and must remain within quotation marks
  • Some of the more complicated settings require that you define what is called an ARRAY in Perl language, and write within parentheses, assigning single or associated keys-values settings. Follow the explanations for that section carefully, and be very careful to place all the necessary single quotes, commas, semicolons, parentheses, etc. exactly as the instructions indicate.
1.  Tax Variables and Configurations

>>> GO TO TABLE OF CONTENTS

What can these settings do?

  • Turn off all tax computations
  • Turn on tax computations for all invoices
  • Turn on tax computations for designated shipping destination only, using one or multiple destinations with individual tax rates for each
  • Assign individual tax rates to match one or more destinations, and assign a default tax rate for all other destinations
  • Set the tax to compute before or after shipping and handling charges
  • Designate one or more destinations to reverse the before / after rule
  • MOF only looks for state matching in the shipping destination address
Configuration details

$use_tax

  • This turns on (1) or turns off (0) using the tax computations.
  • It must be enabled for any computations to occur (1)
  • No tax is computed or printed if turned off (0)
$all_tax
  • This enables (1) computing and printing tax for ALL invoices.
  • Disabling (0) this causes MOF to look only for "state matching" for tax rates.
  • If turned on (1) MOF first looks to see if there are designated tax rates for any defined states in the array below called <%taxrates>. If a match is found, then MOF computes tax from that designated tax rate. If no match is found, or if no states are defined for matching, then MOF uses the default tax rate assigned in <$all_tax>.
  • If turned off (0) then MOF applies a tax only if the shipping destination state is defined or designated in the array below called <%taxrates>. If MOF does not find a state match, then no tax is computed.
$all_rate = 0.03;
  • The default rate explained above if <all_tax> is enabled (1)
  • Use the format 0.0625 with no quotation marks, it is a numeric value
%taxrates = ('STATE',rate);
  • This contains the acronyms of states that you want to tax and rates for each
  • You can define only one('CO',0.03) which applies 3% tax to Colorado destinations
  • Or as many STATEs,rates as you need ('CO',0.03,'TX',0.0625,'OK',0.0825)
  • Which applies a 3% tax if Colorado is the shipping destination
  • or a 6.25% tax if Texas is the Shipping destination
  • or an 8.25% tax if Oklahoma is the destination
  • If you want to use the <all_tax> default rate for all invoices then set this to null.
    • %taxrates = ();
    • This is NOT a zero it is two closed parentheses
Note: you must use only the acronyms in the table provided in the documentation, Appendix 2 – Acronyms for using with State tax matching when setting up this array. MOF can only look for values that were submitted by the drop down box for state shipping destination. You can add to or edit the drop down list in your HTML OrderForm input Page for shipping destination if you want, but you must keep the same definitions here as you have in the input page drop down list.

$tax_before

  • If turned on (1) tax is computed and printed before the S&H charges
  • If turned off (0) tax is computed and printed after the S&H charges
  • The default place to compute and print tax is AFTER the S&H
  • Most states require that S&H is taxed unless exact Shipping charges are computed
  • A few states do not require S&H to be taxed
  • Before this rule is applied MOF looks for any exceptions listed in the next setting
@exceptions = ('STATE');
  • Defines a state or states to be exceptions to the before / after rule
  • Use only the acronyms listed in the Shipping destination drop down list
  • Make sure and follow the exact format using single quotes around STATE
  • Separate multiple states with a comma ('DE','MT','NH','NJ')
Note: MOF will first look for shipping destination states here before it applies the tax_before rule. A state listing here will reverse the rule however it is set. If tax_before is turned off (0) and an exception state is matched, then tax will be computed and printed before the S&H charges, or visa versa.
  • Set the exceptions to null if you don't want MOF looking for anything here.
    • @exceptions = ();
    • This is NOT a zero it is two closed parentheses
2.  Discount Variables and Configurations

>>> GO TO TABLE OF CONTENTS

What can these settings do?

  • Turn off any discount computations
  • Compute a discount for each N number of items - volume discount
  • Compute a discount for each X number of dollars - percentage of dollars spent
  • Compute a discount as a one-time rate by number of products or dollars spent
  • Limit the discount to a minimum / maximum amount
Think about the discount in these two ways:
  • As a percentage of the total dollars spent
  • Or as a set rate per N number of items purchased
These settings apply simple discount rules and rates globally, they cannot produce an arbitrary discount schema that is uneven. The settings can apply a set rate to a set number of products, or a set percentage or dollar amount to a set number of dollars, or a one-time discount for a set number of products or set dollar amount, and/or within one-time minimum or maximum limits.

Here is an example of an uneven discount schema, which cannot be produced by MOF settings, but can be produced by custom code:

Discount $ 2.00 first 3 products, and $ 1.00 every product thereafter until 10 products are purchased, then discount every additional purchase $ 1.50.
  • The discount is subtracted from the gross amount, off the top.
  • All the remaining computations are based on that sub total, the net amount.
  • The handling and shipping computations are based on the amount after discount.
  • The tax is computed on the Net Amount if before S&H
  • However S&H is always based on the sub total after discount, the net amount.
  • And tax is computed on the [Net Amount + Handling + Shipping] if after
Configuration details

$use_discount

  • Simply turns on (1) or turns off (0) any discount computations
  • No discount is computed or displayed if turned off (0)
  • If turned on (1) and <repeat_discount> turned off (0) then a one-time discount is applied
$rate_discount
  • This is the dollar amount (n) to be applied to the computation rules below
  • There is a direct relationship between this rate and these two settings
    • Number of Products <num_discount> or
    • Amount of Purchases <amt_discount>
$repeat_discount
  • When enabled (1) this tells MOF to apply the rate assigned to <rate_discount> at each interval set by either
    • Number of Products <num_discount> or
    • Amount of Purchases <amt_discount>
  • If turned off (0), then the rate assigned to <rate_discount> is applied only one time when the interval is reached defined by either
    • Number of Products <num_discount> or
    • Amount of Purchases <amt_discount>
$num_discount
  • Defines the increment (n) of total products that MOF will apply the rate in <rate_discount> to:
  • DISCOUNT = rate_discountX (Total products ordered /num_discount)
  • if result > max_discount then discount = max_discount
  • if result < min_discount then discount = min_discount
$amt_discount
  • Defines the increment (n) of total dollar amount that MOF will apply the rate in <rate_discount> to:
  • DISCOUNT = rate_discountX(Total dollar amount of invoice /amt_discount)
  • if result > max_discount then discount = max_discount
  • if result < min_discount then discount = min_discount
Note: You can only enable (1) either Number or Amount to be computed. If you fail to enable either of them, or if you mistakenly enable both of them, then no computations occur.

$min_discount

  • Defing a dollar amount (n) minimum to override computations
  • If (n) is defined, then all discount computations result in at least (n) amount
  • Disable this setting (0) if you do not want a minimum
$max_discount
  • Defing a dollar amount (n) maximum to override computations
  • If (n) is defined, then all discount computations will no exceed (n) amount
  • Disable this setting (0) if you do not want a maximum
Examples of the relationship between rates and increments

>>> GO TO TABLE OF CONTENTS

Compute an exact five percent discount on every dollar spent
$use_discount = 1 turn on the discount computations
$repeat_discount = 1 repeat the computation rule at each increment below
$num_discount = 0 do not use the number of products increment
$amt_discount = 0.01 instead set the amount increment for each penny
$rate_discount = 0.0005 set the rate to 0.0005 for each penny of total amount

Compute a one-time discount of $ 10 on all orders over $ 150
$use_discount = 1 turn on the discount computations
$repeat_discount = 0 turn off repeating the computation rule ( use one time )
$num_discount = 0 do not set a number increment to repeat
$amt_discount = 150 instead set an amount increment to the $ 150
$rate_discount = 10 set the rate of $ 10 to discount

  • As you can see this is a "non-repeating" discount, set to adjust $ 10 after the first $ 150 spent.
Compute a five dollar discount for each $ 100 spent
$use_discount = 1 turn on the discount computations
$repeat_discount = 1 repeat the computation rule at each $ 100 dollars
$num_discount = 0 do not use the number of products increment
$amt_discount = 100 instead set the amount increment for every $ 100
$rate_discount = 5 set the rate to $ 5 for each $ 100 of total invoice amount
  • This results in a five dollar discount for every $ 100 spent. It is not an exact percent on the penny like the first example. The discount is only applied at each $ 100 amount spent. So, a purchase of $ 199 would show only the discount applied to the first $ 100, not the remaining $ 99. The total amount would have to reach $ 200 to get the second five dollar discount.
Note: If you use the minimum / maximum settings, then these setting will test the final output from the computations, and adjust the final amount accordingly.

If we add a $min_discount and $max_discount to the last example then we can create a situation where at least a $ 5 discount is applied regardless of how much is spent, and the discount does not go over $ 20.

Compute across the board a $ 5 discount but not to exceed $ 20 with the last example
$min_discount = 5 set the minimum to compute to $ 5
$max_discount = 20 set the maximum to compute to $ 20

Compute a $ 10 volumediscount for each 10 products purchased
$use_discount = 1 turn on the discount computations
$repeat_discount = 1 repeat the computation rule for each 10 products purchased
$num_discount = 10 compute the rate each time 10 items are purchased
$amt_discount = 0 and do not use the amount interval
$rate_discount = 10 set the rate to $ 10 for each 10 of total products purchased

  • Again, because of the relationship between increment and rate, the $ 10 is only credited when a full 10 items have been purchased. Once would not receive any discount for 9 products, and one would only receive $ 10 for 19 products. Change the increment to 1 and the rate to 2.75 and a $ 2.75 discount would be applied for every product purchased.
3.  Handling Variables and Configurations

>>> GO TO TABLE OF CONTENTS

What can these settings do?

The exact same things as the settings for discount explained in the preceding section.

  • Turn on / off switch for computing handling charges
  • Computing a one-time handling charge
  • Computing a Percentage handling charge
  • Computing a Bulk or Volume handling charge
  • Limiting to a minimum or maximum handling charge
Configuration details

The handling computations work exactly the same way as the discount, except they are, of course, added to the sub total after discount. The exact same schema is used. You can assess volume handling charges, a one time charge, or a percentage handling charge.

Compute a five cent handling charge for each dollar spent
$use_handling = 1 turn on the handling computations
$repeat_handling = 1 repeat the computation rule at each defined increment
$num_handling = 0 do not use the number of products increment
$amt_handling = 1 instead set the amount increment for each dollar (1)
$rate_handling = 0.05 set the rate to 0.05 for each $ 1 of total amount

Shipping Configurations - Introduction

>>> GO TO TABLE OF CONTENTS

The shipping computation schemas follow rules that are very similar to the rules we have already been studying for Discount computations and Handling computations.

Here's a quick list of what the shipping configurations do:

  • Automatically detect an out of Merchant Country "foreign" rate
  • Allow the Customer to select between "standard" or "express" rates
  • Settings to define what are "standard" and "express" shipping options
  • Settings to use a default "standard" or "express" shipping rate
  • Configurations to compute shipping charge by weight, volume, amount, minimum, maximum, foreign, domestic, standard, express
The shipping computation rules work on a dollar amount, or a number quantity. The dollar amount rules use the Total Amount of products after a discount, the
  • Sub Total After Discount
If no discount is being used, then the rules use the Total Amount of products. Both shipping and handling charges are always using one of the two totals:
  • Total Amount with no discount or
  • Sub Total After discount
  • Shipping and handling charges are always computed independent of any tax assessed.
  • Shipping and handling charges are always computed independently of each other
  • The number quantity is based on the ShipCodes and not on the quantity of products.
There are two sections to understanding Shipping Charges:
  • Determining which set of rates the computation rules will use
This is covered in the section - Shipping Configurations - Methods Settings
  • Setting the computation rules
The Methods Settings and Computation Settings in the Global and Individual schemas interact together. Both Global and Individual schemas have settings for each of the four methods that can be use.
4.  Shipping Configurations - Methods Settings

>>> GO TO TABLE OF CONTENTS

What can these settings do?

  • Automatically detect a foreign or domestic shipping destination
  • Allow the customer to select a standard or express shipping method
  • Assign your own custom message to define "standard" or "express"
  • Assign a default method (standard or express) and disallow customer selection
Configuration details

Four sets of rates can be used:Standard, Express, Foreign Standard, Foreign Express. So, you are able to use four different sets of rate variables which will be applied to the computation rules. The particular set of rate variables being applied to your computation rules, depends on how you configure the following options:

  • Auto-Detect where a foreign rate is needed
  • Chose between a standard or express rate
If you want to use a Foreign Rate, then you must enable the Auto-Detect Foreign Country feature. If this feature is disabled then you will not be able to apply out of country shipping rates, as all rates will be handled as either Standard, or Express only, with no use of "foreign shipping charges."

Enable this feature by:
$use_ship - 1
$use_country = 1
$match_country = "Merchant Country"

Note: the "match_country" value must come from the drop down list on the OrderForm. You must use one of the exact Country names in the Select Country Names section found in this documentation - Appendix 3. Whenever a shipping destination uses a Country other than the Merchant Country defined in "match_country" then a foreign rate is applied.

Two other sets of rate variables can be applied to the computation rules--Standard or Express shipping rates. You can allow the Customer to choose between these two methods by enabling the "use_rates" switch. This will place two radio buttons on the "Select Quantities - Verify Information" page allowing the Customer to select an Express rate if desired. When you enable this feature, the default rate is "standard" unless the Customer changes it to Express. You can also place your own text defining what is meant by "standard" and what is meant by "Express".

The settings to use this feature are:
$use_rates = 1 allow the customer to choose between express / standard rates
$msg_standard = "However you define what standard is"
$msg_express = "However you define what express is"

If you don't want the Customer to choose between "standard" or "express" rates, then you can disable the "use_rates" feature, but you must then set a default rate to be used in the computation rules.

Disable Customer choices, and enable a default "standard" rate like this:
$use_rates = 0 do not let the customer choose between express or standard
$use_standard = 1 instead set the default rate as standard
$use_express = 0 and don't default as express

Disable Customer choices, and set a default "express" rate like this:
$use_rates = 0 do not let the customer choose between express or standard
$use_standard = 0 don't use standard as the default rate
$use_express = 1 but use express as the default rate instead

Note: you may not have both the "use_standard" and "use_express" switches enabled. If you do this then nothing will be triggered for defining what the default rate is. If you have the Customer choices enabled, then it doesn't matter what you have placed in the default settings, it will be overridden by the "use_rates" Customer choices.

Note: when you get to the next section "Setting the computation rules," then you will see that there are settings for all four Methods --standard, express, foreign standard, express foreign. Make sure that you have placed values in all of the sets of rate variables that you will be using in your particular Method configuration.

For example, if you don't use the Customer choices feature, and you don't use the Out of Country feature, and want to apply a $ 0.35 per pound standard rate set to all invoices, and you don't want a minimum or maximum limit, then you only need to have values for the "standard" set of rate variables:

Only standard set of rate variables:
$use_ship = 1 turn on shipping charges
$use_country = 0 doesn't matter if foreign or domestic
$use_rates = 0 customer doesn't have choice for standard or express
$use_standard = 1 the standard settings are the default
$repeat_shipping = 1 for every increment in $num_shippping repeat computation
$num_shipping = 1 apply the rate 0.35 to each 1 pound of weight
$min_standard = 0 don't use a minimum amount
$max_standard = 0 don't use a maximum amount
$rate_standard = 0.35 apply 35 cents per pound

For another example, if you will be using all four possible options -- standard, express, foreign standard, express foreign, and you want a minimum shipping charge for any of these options, then you will need to give all sets values. If you leave these setting out, then the computations will attempt to act on a zero, which will zero out your shipping charges.

The rule is -- make sure and place values for any of the four shipping rate methods that your particular configuration will be using.

5.  Shipping Configurations - Global Settings

>>> GO TO TABLE OF CONTENTS

What can these settings do?

For any one of the four methods the Global settings can:

  • Compute shipping as actual percentage of dollar amount spent
  • Compute shipping using shipcodes as weight per product by a rate
  • Compute shipping using shipcodes as shipping price per product
These settings cannot produce an uneven shipping schema. They use set rules to produce global rates. You have four types of methods and rates that are applied globally.

This is an example of an uneven shipping schema:

From 1 to 3 products ordered charge $ 3.50 and then charge $ 1.00 for each item after that, up to a total of 15 products, then the shipping charge is free.
While the actual code to compute this example is fairly simple, and can be custom written in perl code embedded in the special shipping section, the global rules cannot produce an uneven computation like this.

Configuration details

The Global shipping computation rules work with the same strategy as the discount or handling computations. The computations can be adjusted to work with weight or dollar amount, and they can be set for a one-time charge, or a repeating computation.

As already mentioned, the simplest way to think about ShipCodes using the "Global Settings" is to think of computing a rate per weight or cost per item.

When using the ship code computation rules you are computing thusly:

  • shipping charge = rate X [ ( shipcode X quantity ) / increment ]
  • The number quantity is based on the ShipCodes X Quantity of products, and not on the quantity of products alone.
  • When you use the $num_shipping increment you are using the actual ShipCode settings you made in your HTML OrderForm input Page.
If you are using the dollar amount then you are computing this way:
  • shipping charge = rate X ( sub total after discount / increment )
  • But, when you use the $amt_shipping you are not using the ShipCodes, you are using an option to compute shipping charges based on total invoice dollar amount.
Understanding the computation rules:

There are four sets of rates -- standard, express, standard foreign, express foreign
The computation rules will be applied to the set of rates for the selected Method

You define the "computation rule" with the following three variables. Then, depending on the Method selected, the "computation rule" is applied to the appropriate set of rates.

$repeat_shipping

  • When enabled (1) this tells MOF to apply the shipping rate resulting from one of the four shipping methods at each interval set by either
    • Total quantity of shipcode values <num_shipping> or
    • Amount of Purchases <amt_shipping>
  • If turned off (0), then MOF will apply only a one-time rate resulting from one of the four shipping methods at the interval set by either
    • Total quantity of shipcode values <num_shipping> or
    • Amount of Purchases <amt_shipping>
$num_shipping
  • Defines the increment (n) of total shipcode values that MOF will apply the designated shipping rate to:
  • SHIPPING = rateX [ ( shipcode Xquantity ) / increment ]
  • if result > method maximum then shipping = method's maximum
  • if result < method minimum then shipping = method's minimum
$amt_shipping
  • Defines the increment (n) of Total Dollar Amount that MOF will apply the designated shipping rate to:
  • SHIPPING = rateX ( Total Dollar Amount/increment )
  • if result > method maximum then shipping = method's maximum
  • if result < method minimum then shipping = method's minimum
If you enable the "repeat_shipping" switch, then the computation rule repeats for every N number of increments, or every N dollar amounts. You set which increment to use, either a number increment "num_shipping" or a dollar increment "amt_shipping" by assigning the increment value to which one you want to use, and leaving the other one set to zero.
Examples of Global Shipping Rates

>>> GO TO TABLE OF CONTENTS

Calculate a "standard" shipping charge of $ 0.35 per pound with a minimum $ 3.95 shipping charge:
$repeat_shipping = 1 repeat the computation rule for every increment
$num_shipping = 1 set the number increment to 1 ( pound )
$amt_shipping = 0 do not use the amount increment
$min_standard = 3.95 make sure there is a minimum $ 3.95 standard shipping charge
$max_standard = 0 there is no limit to assessing 35 cents per pound
$rate_standard = 0.35 set rate to 35 cents per each 1 ( pound )

The num_shipping increment is 1 ( whatever ), so a 0.35 rate is applied to every 1 (whatever) units, and if minimum rate is set, then the minimum will be assessed, until the rate is over that value -- then anything over $ 3.95 is computed at 35 cents per 1 (whatever). The ShipCodes in your HTM OrderForm input Page are relative and can be anything; however, you need to have some plan for your ShipCodes so that computations are meaningful.

Now, make sure and set all the other rate values if you are using all four methods. For example, if you have enabled $use_country and $use_rates then it is possible that any one of the four sets of rates may be selected. So, you need to make sure you have all four sets of rates defined.

Note: the above example assumes that you used a "weight" schema for assigning ShipCodes in your HTML OrderForm input Page.

Note: you only get to configure one computation rule. For example, you can't calculate an "express" shipping charge of $10.50 for anything from 1 to 10 pounds, and then assess a $1.25 per pound rate for anything over 10 pounds. This rule really uses two different increment settings.

You can also just use a configuration based on the Total dollar Amount of products purchased, for example:

Set up rates that would include insurance based on dollar value.
$repeat_shipping = 1 assess $ 1.35 to every $ 10 spent
$num_shipping = 0 do not use the ShipCodes schema
$amt_shipping = 10 instead compute $ 1.35 for each $ 10 spent
$min_express = 12.95 make sure there is a minimum $ 12.95 express shipping charge
$max_express = 0 there is no limit for maximum
$rate_express = 1.35 set rate to $ 1.35 for every $ 10 spent

Note: you can't use one set of computation rules for "standard" and another set of rules for "express." You can only create one set of computation rules which will be applied to whichever set of rates is chosen by the method configurations.

6.  Shipping Configurations - Individual Item Code Settings

>>> GO TO TABLE OF CONTENTS

What can these settings do?

  • Group products together by shipcode and
  • Apply a set of different rates to each group
The way to think about the individual item system of shipping definitions is to think of a shipping cost per item, rather than a cost per pound as in the "global" ( weight ) examples. All products with a ShipCode of 1 may cost $ 0.35 cents to ship "standard" Method, yet cost $ 0.75 cents to ship "foreign standard" Method. Then, all products with a ShipCode of 2 may cost $ 1.35 to ship "standard" Method. So, you can set each Method's rates for each different ShipCode used, then assign your products to groups of ShipCodes, or give all products their own unique ShipCode.
An overview of how it works

>>> GO TO TABLE OF CONTENTS

  • When $use_items has a positive integer value you have enabled this feature, and No Global rates will apply. If $use_items is disabled, then whatever you have set in the Global settings will be used.

  •  
  • Set the value of $use_items to the number of ShipCodes you want in your system of individual definitions.
  • Now, you will define the settings for each individual ShipCode by giving values to a 12 item array for each ShipCode in your system. In the configuratoin file packaged with Merchant OrderForm there are 4 sets of example definitions:
  • @items1 = (3.95,5,0.25,4.95,6,0.55,4.95,6,0.65,5.95,0,1.05);
  • @items2 = (4.95,6,0.35,5.95,7,0.65,5.95,7,0.75,6.95,0,1.15);
  • @items3 = (5.95,7,0.45,6.95,8,0.75,6.95,8,0.85,7.95,0,1.25);
  • @items4 = (6.95,8,0.55,7.95,9,0.85,7.95,9,0.95,8.95,0,1.35);
  • Lastly, any minimum / maximum settings you have for the four sets of Global Settings, will be applied after all individual computations are made, as an overall minimum  - maximum. So, make sure these are set to zero if you don’t want this last test computation to occur.
How to set up the array elements

>>> GO TO TABLE OF CONTENTS

With each array @items1 you are basically creating individual definitions as you did in the section above on "Global Settings." The "Global Settings" has 12 values defined:
 

  • $min_standard 
  • $max_standard 
  • $rate_standard 
These set the values to be used in computations whenever the "standard" rate Method has been chosen
  • $min_express 
  • $max_express 
  • $rate_express 
These set the values to be used in computations whenever the "express" rate Method has been chosen
  • $min_Fstandard 
  • $max_Fstandard 
  • $rate_Fstandard 
These set the values to be used in computations whenever the "Foreign Standard" Method has been chosen
  • $min_Fexpress 
  • $max_Fexpress 
  • $rate_Fexpress 
These set the valued to be used in computations whenever the "Foreign Express" Method has been chosen

The 12 elements in the item arrays correspond to these same settings. Remember to be very careful in making these arrays, and keep commas exactly between each of the 12 values as in the examples included in the packaged configuration file. Here's what the elements correspond to:
 

Standard Method
Express Method
Standard Foreign
Express Foreign
min
max
rate
min
max
rate
min
max
rate
min
max
rate
0
0
0.35
0
0
0.45
0
0
0.55
0
0
0.65

The above example has set No minimum or maximum rules, but has set the following rates to be computed for this ShipCode (let's say it's ShipCode 1):

If the "standard" Method was selected a $