• 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

Merchant OrderFormv1.4 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

Merchant OrderFormv1.4 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:

• Working with settings in the configuration file

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

• A collected FAQ about the Merchant Order Form v1.4

• What is Merchant OrderForm?

• Quick Start Instructions
  • How to get the program running in test mode

• Setting up your OrderForm input page
  • Ways to customize your OrderForm input page
  • What are those other files in the package?
  • Adding products to the HTML OrderForm input Page.
  • How to think about using the ShipCodes
    • Using the Global Settings
    • Using the Individual Item Settings
    • Writing your own code for shipping

• Working with settings in the configuration file
  • Basics about editing the configuration file
  • Tax Variables and Configs
  • Discount Variables and Configs
  • Handling Variables and Configs
  • Shipping Configurations - Introduction
  • Shipping Configurations - Methods Settings
  • Shipping Configurations - Global Settings
  • Shipping Configurations - Individual Item Code Settings
    • An overview of how it works
    • How to set up the array elements
    • Some more examples
    • Some things that go without saying
  • Installing Custom fields
  • Other Switch functions
  • Return Link Settings
  • Merchant Information
  • File Locations
    • These are the files needed by the scripts
    • A quick note about absolute addressing
    • Setting file locations
    • Setting the delimiter used with the RDB log files
  • Merchant and Customer Mail Options
    • Where you send the mail to
    • Now, you're ready to send some mail

• An important note about security.
  • Use SSL on a virtual domain when available
  • Keep the mail off the internet or use PGP

• A checklist for installing CGI on Unix type servers.

• A collected FAQ about the Merchant Order Form v1.4
  • Can I do this with the shipping configurations ?
  • Can MOF accept input from multiple OrderForms ?
  • Can MOF submit totals to my Online Authorization Service ?
  • Is MOF compatible with MS FrontPage 9x ?
  • Basic trouble shooting tips.
  • Error opening DAT files or RDB files.

• Appendix 1 – Name - Value pairs used in the OrderForm input Page
• Appendix 2 – Acronyms for using with State tax matching
• Appendix 3 – Names used for Country Matching
• Appendix 4 - Structure of the related RDB files

Merchant Order Formv1.4 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

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.4 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

• 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.

• Next, you need to set correct file Permissions on the files you just sent to your server's CGI-BIN.

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.
 

• 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

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.

• http://www.io.com/~rga/cgi-bin/orderform14.cgi
• http://www.io.com/~rga/cgi-bin/ordercount14.cgi
• http://www.io.com/~rga/cgi-bin/orderfinal14.cgi

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">

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.

• ordersample14.html
• ordersample24.html

• 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.

• 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

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 files named <show1.html> through <show9.html> are the picture windows. If you use this set up, you'll need to add the images into the HTML windows.

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.4 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

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 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.4 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

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"

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

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:

• Tax variables and configurations
• Discount variables and configurations
  • Examples between Rates and Inrements
• Handling Charges variables and configurations
• Shipping Configurations Introduction
• Shipping Methods configurations
• Shipping configurations - Global Settings
  • Examples of Global Shipping Configurations
• Shipping configurations - Individual item code settings
  • An Overview of how it Works
  • How to set up the array elements
  • Exmaples of Item Code settings
• Enabling Custom fields
• Other switch functions
• Return Link Settings
• Merchant Information
• File locations
• Merchant and Customer mail settings

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:

• 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.

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

$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)

• 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.

• 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

• 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

$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

• 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')

• 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

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

• As a percentage of the total dollars spent
• Or as a set rate per N number of items purchased

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

• 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

$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

• 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>

• 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>

• 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

• 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

$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

• 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

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.

• 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.

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.

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

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

• Sub Total After Discount

• 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.

• Determining which set of rates the computation rules will use

• Setting the computation rules

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

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

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

This is an example of an uneven shipping schema:

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.

• 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.

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>

• Defines the increment (n) of total shipcode values that MOF will apply the designated shipping rate to:
• SHIPPING = rateX [ ( shipcode X quantity ) / increment ]
• if result > method maximum then shipping = method's maximum
• if result < method minimum then shipping = method's minimum

• 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

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

• 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.

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:
 

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:
 

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 $ 0.35 rate would be applied to the total quantity of products that had a  ShipCode = 1. When the script finds a product ordered with the ShipCode = 1, then it goes to the array @items1 and extracts the settings for whichever Method is active.

Important: you must at least enter a zero for each element, and you must separate each element with a comma.

When you set @items2 with a completely different set of definitions, then you can create extremely individual rates. The "standard" rates for all products with a ShipCode = 2 could be very different than the rates for ShipCode = 1.
 

Examples of Item Code Shipping settings

>>> GO TO TABLE OF CONTENTS

If you wanted to give all orders with the ShipCode = 1 a minimum of $ 12.50 for the Express Foreign method no matter how many number 1 items were ordered, and anything after $ 12.50 would adjust an additional $ 0.50 per each number 1 item ordered, then:

$use_ship = 1
$use_items = N where "N" is the number of unique item arrays you will be using
@items1 = (0,0,0,0,0,0,0,0,0,12.5,0,0.5)

If you wanted to make sure that a minimum of $