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

NetMerchant Shipping and Tax Calculations
   
 
 
NetMerchant Shipping and Tax Calculations

Netmerchant uses simple text files to compute charges and discounts such as tax or shipping. These calculation files tell the program whether the charge is constant or variable, and the amount to add to the order. There are two sections to this discussion: You can use the setup tool to copy the default calculation template files to your www/data/shopname folder. In order to create a working version of your shop you will want to FTP these files to yourself and edit them as shown below.




Section One: ABOUT CALCULATIONS
  • If NetMerchant sees a FORM field whose "name" begins with x_, x_a_ or x_s_, it will perform a calculation on this field. The "value" tells NetMerchant the name of the file to use to figure out the charge by becoming the prefix of the calculation filename: value.calc. For example:
    • International Shipping Charges: On the shipping page, the field <input type="checkbox" name="x_intl" value="intlship"> will look for a file called intlship.calc to determine what calculation to use. The value <! x_intl> could be used on subsequent pages to display this charge. The amount is automatically added to the total.
    • Tax Calculations: The field <input type="hidden" name="x_tax" value="tax"> will look for a file called tax.calc to determine what calculation to use. The value <! x_tax> could be used on subsequent pages to display this charge. The amount is automatically added to the total.
    • Handling Charges: A hidden field on the shipping page could look like this: <input type="hidden" name="x_handchg" value="handling"> with a file called handling.calc that includes a Basic value of say $4.00. The value <! x_handchg> could be used on subsequent pages to display the handling charge. The amount is automatically added to the total.
    • x_a_ does the calculation on the subtotal + non-shipping discounts.
    • x_s_ does the calculation on the subtotal + everything including shipping.
  • The same is true for the special field shiptype on the shipping page. The value Reg_Ground, for example looks for a file called Reg_Ground.calc to find out how to figure the shipping charge for this option.

    Calculation Results: The amount calculated is available to you as a new template tag. This new tag, <! x_name>, would thereafter be replaced by this calculated value. The example code above would enable the template tag, <! x_tax>.

    Types of Calculations

    The charge calculated can be a flat amount or a percentage, can be positive or negative and can be static or incremented.

    A flat charge adds a set monetary value (ie. 19.99 without a denomination symbol such as a dollar sign) to the working total. For example, overnight shipping might always cost $9.95 so you might have a file called overnight.calc that looks like this:
       Basic
       9.95
    
    A percentage charge calculates a percentage of the subtotal, and adds this value to the working total. The subtotal used in a percentage calculation is the sum value of all items ordered. A percentage charge is specified as the percentage amount then a percent sign (19.99%). For example you might have a file called tax.calc with tab delimited records that looks like this (the first line uses a space rather than a tab):
            byfield billstate
            IN        5%
            Indiana   5%
            Ind       5%
            Ind.      5%
Note: The field (billstate in this example) must be a field that is remembered by NetMerchant, so it must be billwhatever, shipwhatever, v_whatever or x_whatever rather than just any made up field.

When using ByField, NetMerchant looks for an exact match, ignoring case, between the FORM field value (ship or bill field only) and each string in the calculation file. If a shopper fills in the FORM field manually, they are likely to make make typos or use odd abbreviations. You could list out all possible abbreviations and typos you can think of in the data file (as was done in the example above), but it is safer to use an option list or other fields where the values are pre-defined as is done in our demo example.
A negative charge is a discount. You specify this by putting a minus symbol in front of the flat or percentage charge, for example '-10%' or '-25.50'.

An incremental charge is where you increment the charge based on the order quantity (ByQuantity) or subtotal (BySubtotal). In this case, the first value is the amount to compare against the subtotal or quantity, and the second value is the charge. Thus, you might have a file called Reg_Ground.calc that looks like this:
BySubtotal
10      2.50
20      3.75
30      5.25
40      5.80
50      6.10
over    6.50
You read the above file like a price schedule. If the order's subtotal is $10.00 or less, this calculation's charge is $2.50; if the subtotal is $20.00 or less (so, $10.01-$20.00), the charge is $3.75; and so on. NetMerchant uses the first line of the file to decide which value to compare to (in this case, the subtotal), then moves down line by line seeing if this value is less than or equal to the first field of the line. If a match is made, the second field on that line is the charge for the calculation.
A complex charge can be developed by calling a new calc file from the orignal calc file. For example, your client ships out of Washington state and need to charge sales tax to WA residents. You currently have a calc file called tax.calc that looks like this:
byfield shipstate
WA      8.75%
but you just found out that King County wants needs to charge an extra .5% sales tax to fund flowers at the base of the space neeedle... furthermore, Garfield county is all Native American Reservation land and is exempt from sales tax... but you can't just do byfield shipcounty since Kansas City is in King County Kansas and who knows how many Garfield Counties there are... so you do this by calling a county calc file from your state calc file like this in your tax.calc file:
byfield shipstate
WA      tax1.calc
where tax1.calc has the percentages for every county like this:
byfield shipcounty
Adams       8.75%
Asotin      8.75%
Benton      8.75%
...
Garfield    0
...
King        9.25%
...
etc


Section Two: SHIPPING CALCULATIONS

Since charges may be fixed or may vary as the size of an order varies, NetMerchant provides several types of calculations you may use. Examples of these are shown below. You define which type to use by putting one of these strings as the first line of your calculation file:
  • Basic - always charges a fixed amount
  • ByQuantity - the charge varies according to the number of items ordered
  • BySubtotal - the charge varies according to the $ amount of the subtotal of the order
  • ByField - a FORM field is tested and the charge varies depending on whether a bill or ship field matches expected values
  • ByItem - the charge is specified for every item
  • ByWeight - the charge is calculated based on shipping weight
  • ByUPS - the charge is calculated based on shipping weight but uses real-time calculations from UPS
  • Combinations - You can use byItem instead of a number or percentage when using bySubtotal, byQuantity or byField. If a level is matched and the value of that level is "byItem" the total of the 4th column for the items in the basket is used as the value.
  • shipping.conf - A file called shipping.conf can be included in your /data/shopname folder. This file allows additional manipulation of the shipping costs both by field and in other ways..
Basic - Used if you need a flat charge to add a set monetary value (ie. 19.99 without a denomination symbol such as a dollar sign) to the working total. For example, overnight shipping might always cost $9.95 so you might have a file called overnight.calc that looks like this:
Basic
9.95
ByQuantity and BySubtotal - Used if you need to vary the charge based on the order quantity (ByQuantity) or subtotal (BySubtotal). In this case, the first value is the amount to compare against the subtotal or quantity, and the second value is the charge. Thus, you might have a file called Reg_Ground.calc that looks like one of these:
   BySubtotal    or   BySubtotal      or   ByQuantity
   10      2.50       1499    byItem       10     3.75
   20      3.75       1500    0            20     6.00
   30      5.25                            over   other.calc
   40      5.80
   50      6.10
   over    6.50
You read the above files like a price schedule. For the file on the left, if the order's subtotal is $10.00 or less, this calculation's charge is $2.50; if the subtotal is $20.00 or less (so, $10.01-$20.00), the charge is $3.75; and so on. NetMerchant uses the first line of the file to decide which value to compare to (in this case, the subtotal), then moves down line by line seeing if this value is less than or equal to the first field of the line. If a match is made, the second field on that line is the charge for the calculation. For the file in the center, up to $1499, the total of the 4th column for the items in the basket is used, above $1500, shipping is free. For the file on the right, up to 10 items is $3.75, 11 to 20 is $6.00 and over that is based on the calculations found in the file other.calc which could be any one of the other calculation methods.

ByItem - Used if you must have a specific shipping charge for every item. In order for this to work, you must add a fourth column to your shopname.data file where you specify the exact shipping charge for every item. If all the items had the same charge, you would probably use ByQuantity. However, if for example, you had specials with special shipping costs, you might use a file called Reg_Ground.calc that looks like this:
      ByItem
The following template tags are associated with this option.
  • <! UNITSHIPCOST> - Will be replaced for each item in the basket by the value specified for the item in the fourth column of shopname.data.
  • <! NETSHIPCOST> - Takes the number above and multiplies it by the quantity of the item that was ordered.
ByWeight - Used if you must calculate shipping charge based on weight. In order for this to work, you must add a fourth column to your shopname.data file where you specify the exact shipping weight for every item. NetMerchant adds up the weight and provides a total upon which it bases the calculation. Thus, you might have a file called Reg_Ground.calc that looks like this:
   ByWeight
   1       2.50
   2       3.75
   3       5.25
   4       5.80
   5       6.10
   over    6.50
The following tags are associated with this option:
Itemloop Tags:
  • <! UNITWEIGHT> - Will be replaced for each item in the basket by the weight specified for the item in the fourth column of shopname.data.
  • <! NETWEIGHT> - Takes the number above and multiplies it by the quantity of the item that was ordered.
Other Tag:
  • <! TOTALWEIGHT> - This will be replaced by the total calculated weight of the order.
ByUPS - If you use shipping by weight and have a UPS account, you can calculate the shipping cost based on real-time calculations from your vendor. In order for this to work, you must add a fourth column to your shopname.data file where you specify the exact shipping weight for every item. NetMerchant adds up the weight and provides a total for UPS to use. In addition to the weight, your vendor needs the zipcode you are shipping from, the customer's zipcode and several other items. Details are provided here.

shipping.conf - A file called shipping.conf can be included in your /data/shopname folder. This file allows additional manipulation of the shipping costs both by field and in other ways. An example shipping.conf file follows. Note: the white space is a tab:
     max     20
     min     1
     shipstate=HI    -10%
     shipstate=TN    5.00
     shipstate=TN&shipcity=Nashville&shiptype=basic&subtotal>39.00    0
     shipstate=HI    10.50
The file reads from top to bottom. Shipping is first calcluated via traditional methods. Then these conditions are tested. So this reads
  • if the calculated shipping is greater than 20, set it to $20
  • if the calculated shipping is less than 1, set it to $1
  • if the shipping state is Hawaii, subtract 10% from the shipping cost.
  • if the shipping state is Tennessee, set shipping to $5.00
  • if the shipping state is Tennessee AND the shipping city is Nashville AND the shiptype is "basic" AND the subtotal is greater than $39, shipping is free
  • If the shipping state is Hawaii, add $10.50 to the shipping cost, which overrides the previous instruction.




Section Three: ADVANCED CALCULATIONS

By using a calc file with a numerical value as its name, a numerical value may be passed into calculation fields (x_fieldname, x_a_fieldname, x_s_fieldname, shiptype) and be used directly AS that value. This is not meant to replace the traditional calc file method described above, which is already quite powerful and even allows for nested calculations. If the value of one of these calculation fields is non-numerical, the traditional calc file method will be used. For example:

<input type="hidden" name="shiptype" value="basic"> will point netmerchant to the calc file "basic.calc"
<input type="hidden" name="x_a_tax" value="tax"> will point netmerchant to the calc file "tax.calc"

However, the following will now behave differently:

<input type="hidden" name="shiptype" value="5.01"> will set the shipcost to $5.01
<input type="hidden" name="x_discount" value="-10"> will set x_discount to -$10.00 and subtract that amount from the total

This change is meant, primarily, to be a tool for advanced programmers. In combination with the ! include tag, a PHP or ColdFusion script can be called upon to do whatever sort of complex calculations your shopping cart requires and then simply return the value of those calculations as a numerical value in a hidden field like those above, thus, passing that value into the cart and into NetMerchant for checkout.

How NetMerchant stores values for those with SQL enabled:

Netmerchant stores it's values in your local database, which can be accessed using either PHP or ColdFusion and your database username and password. When NetMerchant runs for the first time on a SQL-enabled hosting account, it creates the following tables:
  • nm_files
  • nm_itemloop
  • nm_nmbid
  • nm_nmoid
  • nm_paypal
  • nm_shipbille
Relevant information is keyed off of <! BID>. Therefore, <! INCLUDE_LAST pagename.php?bid=<! BID>> will give you access to everything NetMerchant uses while in a PHP or ColdFusion script environment. The table you really care about above is nm_itemloop.
ICG Link, Inc. 7003 Chadwick Drive, Suite 111, Brentwood, TN 37027