The USPS plug-in requires you to have the following Perl Modules installed on the server:
To test for these modules, we suggest getting a copy of 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.
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 https://secure.shippingapis.com/registration/
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.
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:
Put the following files directly in your cgi-bin directory:
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.
At a minimum, you need to set these 2 variables:
usps_user_id=YOUR USPS Username
usps_password=YOUR USPS Password
test_mode=yes
usps_origin_postal_code=20770
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.
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:
Then, you should be able to get live rates from USPS...
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 ( : )
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 (10 lbs. 2 ounces)
The Dimensions are defined as: 12x14x20
(length x width x height) - no spaces between the characters
The Package Type is one of 2 entries:
M-3 means use multiple boxes with up to three items per box.
M means use multiple boxes putting all of that item in the same 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:
| Package Name | Value | Description |
|---|---|---|
| Express Mail | NONE | For someone using their own package |
| 0-1093 | Box, 12.25 x 15.5 | |
| 0-1094 | Tube, 36 x 6 | |
| EP13A | Cardboard Envelope, 12.5 x 9.5 | |
| EP13C | Tyvek Envelope, 12.5 x 15.5 | |
| EP13F | Flat Rate Envelope, 12.5 x 9.5 | |
| Priority Mail | NONE | For someone using their own package |
| 0-1095 | Box, 12.25 x 15.5 x 3 | |
| 0-1096 | Video, 8.25 x 5.25 x 1.5 | |
| 0-1097 | Box, 11.25 x 14 x 2.25 | |
| 0-1098 | Tube, 6 x 38 | |
| EP14 | Tyvek Envelope, 12.5 x 15.5 | |
| EP14F | Flat Rate Envelope, 12.5 x 9.5 | |
| Parcel Post | NONE | For someone using their own package |
| Bound Printed Matter | NONE | For someone using their own package |
| Library Mail | NONE | For someone using their own package |
| Media Mail | NONE | For someone using their own package |
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.
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.
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.
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 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:
To setup a product for download only, just use zero (0) in the weight field.
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™, 2-3 Days
Express=U.S.P.S Express Mail®, Overnight
Parcel=U.S.P.S Parcel Post®, Ground Shipment
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.
This variable allows you to change the text used in the result table headers.
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.
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.