home page
JavaScript

Complex Single Item Purchase Demo.

* 2 September, 2004 Fixed tax problem - now multiplied by quantity.
* 23 May, 2004 ZIP code must be entered.
* 6 January, 2004 New and improved.
* 21 August, 2003 Conform to 15 August PayPal release. New variable "lc" must be passed.

The purpose of this is to demonstrate some "plug-in" JavaScript (JS) that can help the Single Item Purchase user of PayPal. It starts with the standard PayPal-supplied HTML from their button factory and makes a few changes to permit the JS interface. You never have to mess with the JS at all - just learn how to interface with it. Here is a list of features...

• User inputs quantity while in your site, not in PayPal. That makes these things work - user cannot change quantities and make the calculations invalid once within PayPal.
• Quantity-based discounts. (You build your own unlimited table)
• Quantity-based amounts. Charge based on qty - unlimited table.
• Quantity-based handling charges. (Your own unlimited table)
• Quantity-based shipping charges. (Your own unlimited table for special situations.)
• Actual USPS Priority shipping charges calculated based on weight.
• User selected shipping options (zones, foreign, air, ground), separate table for each.
• Coupon discounts now supported.
• User selected tax rates. (example uses Ontario model)
• Altered prices for larger or special options.
• Unnamed FORM elements to populate PayPal description field.
  • Select - add value to description and alter price.
  • Select-multiple - add value to description and alter price.
  • Checkbox - add value to description and alter price.
  • Text - just add value to description field.
  • Radio - not supported because they are named. They must be targeted to normal PayPal named fields such as the options fields.
  • Textarea - not supported. Use text.
• New named FORM elements to hold base price and description. (REQUIRED)
  • baseamt - base amount. The cost of each item. Never modified.
  • basedes - base description. Name of an item. Never modified.

Following is an example FORM using the JS. Right-click on this page, and then , so you have a reference to what was done in the HTML to interface with the JS. Play with the FORM and see how it works. Following the FORM is a description of the interface into the JS. It occurs in event handlers within the HTML.

The following quantity-based tables may be constructed. They may be called from different places, just as long as they are called before the FORM is evaluated.

1. Quantity based discount. - SetQD (2, 1, 5, 2);
   • 2 - 4, 1.00 off.
   • 5 or more, 2.00 off.
2. Quantity based amount. - SetQA (1, 10, 6, 9);
   • 1 - 5 10.00.
   • 6 - up 9.00.
3. Quantity based handling charges. - SetHN (1, 3, 2, 5);
   • 1, 3.00.
   • 2 or more, 5.00.
4. Quantity based shipping charges. There are two ways to do this.
   • Only one sort of shipping, just call SetSH (q1, a1); where q and a are quantity/price pairs, like above.
   • You offer different sorts of shipping, or want to specify shipping tables for different weights or places. It is a little complicated and requires that you do two things to set it up. List out this HTML (right click) and the JavaScript (upper-right corner link) to see how I did it in this example.
     1. Include a dropdown named "shp" within the FORM to present your options like is done in this HTML (right-click to see).
     2. Go into the JavaScript function named Shipper and build the shipping tables that correspond to your dropdown with calls to SetSH and other options in the places indicated.
   If you charge no shipping at all then you must make a call in the set-list following the sing.js installation of SetSH (0, 0); This is required to make the program work.

[Picture of item] Blah, Blah... $10.00 each.

Start of FORM

End of FORM

Rules of JS Use

1. You first have to capture the JavaScript (JS). Click the link at the upper right of this page and it will display in your browser. It depends on your browser, but do a <select all> <copy> and <paste> it into your Word Processor (Wordpad works just fine).
   
   From your WP do a <save as> to put the JS where you want it. A good place is in the same folder as your order page. An important part of this save operation is to make sure you are saving the file in pure text format, and not some WP format with controls at the start of it. The main reason for not being able to read the JS file is that is was saved in some WP format.
   
   
2. Assuming that you saved the JS as "sing.js" you add it to your HTML page by including these lines right after the <body>...
   
   

       <script type = "text/javascript"
               src  = "sing.js">
       </script>
   

3. If you are going to use any of the quantity discount, amount, handling or shipping tables, you may make calls to build them in a separate JavaScript selection (after the above selection) in this manner...
   
   

       <script type="text/javascript">
         SetQD (q1, p1, q2, p2, ...);
         SetHN (q1, p1, q2, p2, ...);
         SetSH (q1, p1, q2, p2, ...);
       </script>
   
     where
       q1 = 1st quantity breakpoint
       p1 = amount after q1 breakpoint
       q2 = 2nd quantity breakpoint
       p2 = amount after q2 breakpoint
        etc.
   

   You may also set the weight of the item here, if you are going to use the internal USPS Priority shipping tables (it is probably the best place)...

       SetWT (3.5);  // ounces that a single item weighs
   

   Note: placing them in the onload event handler of the body can get you into trouble because some sites never finish loading because of errors on the page, or references to nonexistant images on other servers. This is the best/safest way.
   
   The tables may be as large as you want them to be, limited only by memory in the customer's computer (because that is where they are built).
   
   
4. Modify the FORM output from the PayPal button factory. This is the hard part (but not that hard). See the listing of the HTML for this page for an example of how I did it.
   • Add an onsubmit event handler to the FORM statement as I did in this page (right-click to see this page).
   • Change the "quantity" element to allow the user to input his own quantity. (see this listing)
   • You MUST delete the "undefined_quantity" input element, if present, from the FORM.
   • Add a new hidden element named "baseamt" whose value is set to the base price of a single item. The "amount" will be plugged from the calculations. PayPal ignores any FORM elements with names it does not recognize (or any unnamed elements), and we need a place to store original values of some things that are never modified so we don't get double discounts and other nasty stuff.
   • Add a new hidden element named "basedes" whose value is set to the base description of the item. This value, along with other values, will be stored in the "item_name" element of the FORM .
   • If you use any of the discount, shipping or handling tables, then you must add corresponding override hidden elements so their calculated values may be plugged. If you do not use a table then do not include a hidden element for it, and let PayPal tables work for you. Be sure to check the button to allow overrides in your PayPal preferences.
   • If you want to set local tax values do it in the manner that I did with a dropdown the user selects from, and use the same onchange event handler. This allows you to do things like must be done in Canada where, for example, Ontario has one tax rate that is different from the rest of Canada, and foreign orders are not charged taxes.
   • If you elect to set up a dropdown for different shipping options then do it in the way I did in this page. If you do NOT want this feature then you must not include the dropdown, and at the top of the HTML add this to the set list - SetSH (0, 0);
   • Now the fun part - letting users select different options for your product (remember, there is a 127 character limit on this, and the JS sticks some stuff in the description field, too). All you have to do is to include all options in unnamed FORM elements! The "value" field of any unnamed FORM element is added to the description sent to PayPal. See the way this page works. You can set a base price "@", or provide price increments "+", or price percent changes "%" in any unnamed field except text and radio. You can charge more for larger sizes, for example. You do this by having the last few characters of the "value" field start with the flag character followed by a valid currency amount - "+1.50", for example. This adds 1.50 (whatever your currency is) to the base price of the item! See this HTML to see how I did it. (right-click on this page)
   • If you are going to use PayPal's tax calculations you must not include the hidden "tax" item in your FORM!

And that is all there is to it. The JS is just a utility that you use and never have to mess with, and you get added features with your Single Item Purchase web page. WARNING - you cannot use many of these features in a shopping cart as coded. Please trust me in this!

Version loads.

Contact me concerning this article at paypalhelper@aol.com. Mention "SIP" in your note.

Individual help starting at $25.00 for simple JS solutions.

Some links to help you with your shipping tables and charges...

* How to build zone/rate tables in JavaScript.
* USPS Zones, and Priority rates.
* UPS Zones.
* FedEx Zones.

These tables may also be used to construct shipping charts with the SetSH function. For example, you may not want to construct a complete shipping table for Europe, so you can approximate charges to those countries by building charge tables with the quantity-based shipping charge builder (SetSH).

I was a little surprised to discover that USPS was cheaper than UPS below the 3-9 pound area, depending on distance and UPS fuel charges. Perhaps the best approach is to calculate several different shipping options for the user, display them and let him take his pick.

The total surprise to me was that you could calculate zone tables for any shipper there is (they all supply this information), and support national or international - depends on how much time you want to spend to set up your tables. It can all be done client-side without the need for a server, or e-commerce solution. Remarkable! But, ya gots to know some JavaScript to do it, huh?

NOTE - you must really read these charts! In the case of UPS there are some zones (Hawaii, Alaska, and the Protectorates) that require special attention. The best solution is, probably, to create special zones for their ZIPs (9, 10, 11, etc) and enter them into your tables (both zone and charge.) Any other solution simply misleads people in these ZIP code areas. USPS is subsidized, and it may be cheaper to ship to those areas that way.