QuikStore USPS XML Rate Calculator Plug-in Setup

Server Requirements

The USPS plug-in requires you to have the following Perl Modules installed on the server:

• CGI
• CGI::Carp
• HTML
• HTTP
• HTTP::Request
• LWP
• LWP::UserAgent
• URI
• XML::DOM
• XML::Parser
• XML::Expat
• WWW

To test for these modules, we suggest getting a copy of PerlDiver:

http://www.scriptsolutions.com/programs/free/perldiver/

Once installed, it will show ALL of the Perl modules installed on the server. You can then contact your web host and have them add
the ones that are missing.

Registering at United States Postal Service

The first thing you need to do once the proper Perl modules are installed is register with USPS Online Tools so you can get a username and password.

Go here to register http://www.uspsprioritymail.com/et_regcert.html

Once you have registered, you will get an email with your "TEST" username and password. We will be using this during the preliminary installation of the plug-in to make sure it's working correctly.

Plug-in Installation Instructions

NOTE: Please be careful reading this section. There may be a couple of entries that are "UPS" and not "USPS". That is because the "ups" entries are in the qs_main files by default. The plug-in name, setup ini, and template file names are what count.

Put the following files in your cgi-bin/plug-ins directory:

• uspsxml.pl
• uspsxml.ini
• usps_enter_data.html
• usps_results.html
  

Put the following files directly in your cgi-bin directory:

• uspstest.cgi
• uspstestxml.txt

NOTE: You will need to manually set the permissions on the uspstest.cgi to 755 (read,execute)

Open your quikstore qs_main.cgi file and set:

use_ups=yes
ups_plugin_name=uspsxml.pl

NOTE: All other variables are now set in the uspsxml.ini file. The remaining variables in the [UPS_SHIPPING] section of the qs_main do not do anything for this plug-in.

1. Open the uspsxml.ini file and change the following variables:

   At a minimum, you need to set these 2 variables:

usps_user_id=YOUR USPS Username
usps_password=YOUR USPS Password

2. For right now, leave the following variables in test mode:
   

   test_mode=yes
   usps_origin_postal_code=20770

3. Once you are in LIVE Mode, you can then go in and set any other variables as you wish in the uspsxml.ini file.
   Each variable in the uspsxml.ini file has been commented as to its' purpose/settings.

Testing The USPS Plug-in

To make sure the plug-in is working correctly, we need to run the test script:

In a browser, enter the URL to the uspstest.cgi script:

http://www.YOURSITE.com/cgi-bin/uspstest.cgi

This should return a list of tests calls to the USPS server. If all of these values got returned correctly, you are ready to go live...

NOTE: USPS will NOT let you go live until these tests have been completed.

Going Live with USPS

Once you have successful tested against the test server and feel you are ready to send requests to the “live” production server you will need to contact the Internet Customer Care Center (ICCC) by telephone or email and they will activate your user ID and password so that you have access to the production server at production.shippingapis.com.

The ICCC is manned from 7:00AM to 11:00PM Eastern Time.
E-mail: icustomercare@usps.com
Telephone: 1-800-344-7779 (7:00AM to 11:00PM ET)

The next thing is to reset a couple of variables in the uspsxml.ini file:

1. test_mode=no
2. usps_origin_postal_code=YOUR SHIP FROM ZIP CODE

Then, you should be able to get live rates from USPS...

Defining the "Packages" for your products

With the USPS (and UPS) plug-in, you can setup EACH product to allow for single, multiple, or order packages.

NOTE: If you do not define the package as shown below, it becomes part of an "order" package. This means that any undefined packages will all go into one box to be shipped. To define an "order" package product, simply enter the weight into the weight field for the product as you would normally.

You can define 5 parameters for each product. Each parameter is seperated by a colon ( : )

1. Weight
2. Dimensions
3. Package Type
4. Box
5. Origin Zip Code

This information is entered into the "Weight" field of the cart. For a database store, it would be entered into the "weight" field in the Catalog Wizard. In an HTML store, it would be entered into the weight field in the "item-" line for defining products in the HTML <FORM>. The is described in the Quikstore Help files under the HTML Store / Quikcode Wizard section.

An example of the USPS entry in the weight field would be:

10.02:12x14x20:S:NONE:13905

The Weight may be entered in LBS and OZ like this: 10.02

Weight Examples:

9.1 = 9 lbs. 10 oz.
9.10 = 9 lbs. 10 oz.
9.01 = 9 lbs. 1 oz.

9.18 will get recalculated to: 10.02

The OZ side of the decimal is a value from 0 to 15. If you want 1 OZ, you must put a zero in front of it (.01)

The Dimensions are defined as: 12x14x20

(length x width x height) - no spaces between the characters

The Package Type is one of 2 entries:

1. S = Ship each item in its' own box (if the user gets 3 of this item, there will be 3 boxes)
2. M = Ship mutiple quantities of this item together in one box.

The Box is defined below. The default value is NONE if left empty. Use the "Value" field listed below.

Here's the list of available selections:

The Origin Zip Code is the zip code that the package will be shipped from. If you leave this empty or set it to NONE, it will use the setting from the uspsxml.ini configuration file.

Debugging The Plug-in

If you want to see the request and response XML, you can turn on the debug flag in the uspsxml.ini file:

debug_usps=1

( 1 = on, 0 = off )

This will show you all of the XML that is created for the request, and the response XML back from USPS along with any error message should they occur.

Handling and Insurance Charges

You may set a "Handling" charge and an "Insurance" charge to be added to results from USPS in the uspsxml.ini file:

handling_charge=2.00

insurance_charge=0.00

The handling charge will be added to each of the services returned from USPS. Should you do this, you should also put some instructions on the usps_results.html that explains that the rates shown include your handling charge.

Selected Services to display

You can set which services will be requested from USPS in the uspsxml.ini file:

NOTE: This is a simple, comma delimited list. The available domestic services are: Priority,Express,Parcel

usps_services=Priority,Express,Parcel

To set the default service that is select when the result page is displayed for domestic shipments:

default_usps_service=Priority

You can also set the default service that is select when the result page is displayed for International Shipments.

default_international_usps_service=Airmail Parcel Post

Note: International services are described below.

Zero Weight Shipping

Zero weight shipping allows you to have a "Download Only" option for downloadable products. If the total weight of the cart is zero (0), it will not contact USPS. It will show the values you set here:

• allow_zero_weight=yes
• zero_weight_default_name=Download Only
• zero_weight_default_price=FREE

To setup a product for download only, just use zero (0) in the weight field.

USPS Label Text

These are simply a list of the text labels displayed in the results table for each service.

Service = Service Label, Number of days to deliver

Priority=U.S.P.S Priority Mail&trade;, 2-3 Days
Express=U.S.P.S Express Mail&reg;, Overnight
Parcel=U.S.P.S Parcel Post&reg;, Ground Shipment

USPS International Services

This is a list of available international services from USPS:

NOTE: put a lb sign (#) in front of the ones you DO NOT want to use

#00=Global Express Guaranteed Document Service
01=Global Express Guaranteed Non-Document Service
02=Global Express Mail (EMS)
#03=Global Priority Mail - Flat-rate Envelope (large)
#04=Global Priority Mail - Flat-rate Envelope (small)
#05=Global Priority Mail - Variable Weight Envelope (single)
#06=Airmail Letter Post
07=Airmail Parcel Post
#08=Economy (Surface) Letter Post
09=Economy (Surface) Parcel Post

You will notice that several of these are commented out. During testing, we found the uncommented ones work best for standard packages. The "Global Express Guaranteed Non-Document Service" is especially important because it is the only value returned for many of the countries. If this service is commented out, the plug-in will not show ANY rates.

Shipping Table Header Fields

This variable allows you to change the text used in the result table headers.

UPS Messages

All remaing variables in the upsxml.ini are for error messages should an error occur. Most all errors will be returned from UPS directly and in this case, the variables in the upsxml.ini are not used. The actual error description sent back from UPS will be displayed.

International Country Codes

These are simply used to convert from the country code, used on the usps_enter_data.html page, to the full text name of the country used in the request XML. There should be no reason to make any changes here.