Lance's TextBox

To complement the previous tutorials I've posted about how to add credit cards to your website or desktop applications, I will be posting a howto for how to add support for PayPal payments, and I'll also begin a series of howto's on how to automate and manage shipping through USPS, FedEx, and UPS.

Update:  FedEx Tutorial here.

I'll start with USPS because there are a lot of questions floating around lately about USPS rates since they have made wholesale changes there.

Mail Yourself?

As I was writing this, I ran across this interesting article in Smithsonian Magazine about a 2 year old boy who was mailed from Oklahoma to Kansas in 1914 for 18 cents!  :)

Registration with USPS

No matter what API you use to communicate with the US Postal Service, you will need to register with them.  Online registration is free and provides developers with a unique username and password that must be used when accessing shipping services. To register for your free username and password, visit: http://www.uspswebtools.com/registration/ .

Connecting to USPS

After you register your account with USPS, you'll have access to their test servers, which support only "canned" tests, meaning that the test servers will only accept certain request data.  This test data is included in the IBiz USPS demos.  After you are ready to go live, you'll need to contact the USPS Internet Customer Care Center and request access to the live production server, where you'll be able to use real data input.  Note:  if you plan to use delivery/signature confirmation (ConfirmationLabels) or merchandise return service (ReturnLabels), you'll also need to contact the USPS National Customer Support Center ((800) 279-2651) to certify your actual printed labels, they will need to know you are an Internet customer using their Webtools services.

For a list of test and live urls, see the section at the end of this tutorial entitled "A Note on Server URLs".

The IBiz USPS Integrator toolkit

IBiz USPS Integrator is a tookit that enables software developers to quickly and easily incorporate USPS shipping capabilities into their software applications and websites.  The toolkit includes the following components:

Shipping Label Generation:

• ConfirmationLabels component, used to generate delivery or signature confirmation labels.
• CustomsLabels, which generates the customs forms needed for international shipments where you have a pre-paid label (ie, aquired from Pitney-Bowes), when shipping surface (sea) mail, or when shipping to APO/FPO addresses.  Labels will be complete with addresses, barcodes, and customs declarations.
• InternationalLabels (formerly the GlobalExpressLabels component), generates shipping labels and customs forms needed for international shipments via International Priority, Express, and First Class mail.
• ExpressLabels, generates a USPS Express Mail shipping label and optionally a customer online record.
• ReturnLabels, generates a printable electronic merchandise return label ("No postage necessary if mailed in the United States").

Rate Retrieval:

• DomesticRates component, used to retrieve dimensional rate information that USPS started implementing in May 2007.  The component provides online automated access to rates based on weight, size, class, and origin/destination for Express Mail, First-Class Mail, and Priority Mail, as well as single-piece rates for package services Parcel Post, Bound Printed Matter, Library Mail, and Media Mail.
• InternationRates component, used to retrieve rate information associated with the InternationalLabels component.

Shipment Delivery Estimation, Tracking, and Scheduling, and Address Verification:

• AddressInfo, used to verify and standardize a customer address, lookup zip codes and city/states.
• CarrierPickup, used to submit an electronic pickup request (a mail carrier will pickup your package at your door when s/he arrives for regular delivery).
• ShippingTime component, provides estimated shipping times between two zip codes.
• TrackAndConfirm, checks delivery status of any package sent Express Mail, US Delivery or Signature confirmation mail, and all International shipments.

Getting Started

Your typical online retailer needs to ship sold items to his customer, and this simple task involves several steps:

1. Get the customer's shipping address, optionally verify it with USPS.
2. Allow the customer to choose what type of shipping to use, show the cost and delivery time of each choice.
3. Print a shipping label for the package.
4. Provide the customer with a shipment tracking number.
5. Schedule a mail carrier to pick up the package.
6. Give the package to the carrier.

Now here is how we can implement each of these tasks.

1.  Get the customer's shipping address, optionally verify it with USPS.

After you get the customers shipping address, you may choose to verify that address with USPS.  Address verification is not required, and most merchants do not need this feature.  If you want to implement address verification, doing so will require special permission from USPS, and USPS will have to specifically activate the address information feature on your account.

The AddressInfo component allows you to verify a complete address (LookupAddress() method), lookup a zip code of a city/state(LookupZip() method), and lookup the city/state of a zip code (LookupCityState() method).  Here is an example of using the LookupAddress method to verify ("standardize") an address:

AddressInfo1.Server = "https://production.shippingapis.com/ShippingAPI.dll"; 
AddressInfo1.UserId = yourusername; 
AddressInfo1.Password = yourpassword; 
AddressInfo1.AddressLine2 = "6406 Ivy Lane"; 
AddressInfo1.City = "Greenbelt"; 
AddressInfo1.State = "MD"; 
AddressInfo1.LookupAddress(); 

Here is the address I want to verify...
Now the address is verified and standardized.

2.  Allow the customer to choose what type of shipping to use, show them the cost and estimated delivery time of each choice.

Now that you have a shipping address from the customer, you can retrieve the cost of delivery and an estimated time of delivery using the DomesticRates (or InternationalRates for international shipments) and ShippingTime components.

To determine the postage rate to ship a regular sized package from my zip code (27502) to the sample address used in the earlier example (20770), I can use the following code:

DomesticRates1.Server = http://production.shippingapis.com/ShippingAPI.dll; 
DomesticRates1.UserId = username; 
DomesticRates1.Password = password; 
DomesticRates1.FromZipCode = "27502"; 
DomesticRates1.ToZipCode = "20770"; 
DomesticRates1.PackagePounds = "1"; 
DomesticRates1.PackageOunces = '4"; 
DomesticRates1.PackageSize = psRegular; //0 
DomesticRates1.ServiceType = svcAll; //7, show all service type costs 
DomesticRates1.CalculatePostage();

Again, here I would use the InternationalRates component if I were shipping internationally.  Note the setting of the PackageSize and ServiceType properties.  Rates depend on location (from and to), size, weight, container (envelope, box, etc), and service type.  Available service types are Priority Mail, First Class, Parcel Post, Bound Printed Matter, Media Mail, Library Mail, or Express Mail.  The ServiceType property has an "all" setting that will tell the component to retrieve rates for all available service types.

Package sizes are defined by USPS as follows:

• Regular, which is defined as:
  Priority Mail: less than one cubic foot in size
  All other service types: length plus girth is 84 inches or less
• Large, which is defined as:
  Priority Mail: greater than one cubic foot in size
  All other service types: length plus girth is between 85 and 108 inches.
• Oversize, which is defined as having a length plus girth of between 109-130 inches.

To compute the shipping time, use the ShippingTime component and simply provide the from zip, the destination zip, and the service type:

ShippingTime1.Server = "http://production.shippingapis.com/ShippingAPI.dll"; 
ShippingTime1.UserId = username; 
ShippingTime1.Password = password; 
ShippingTime1.ServiceType = stPriority; //0, priority mail 
ShippingTime1.GetShippingTime("27502", "20770");

3.  Print a shipping label for the package.

Use one of the Labels components to generate a shipping label for your package.  The components will generate labels in TIF, JPG, PDF, or GIF formats for your printing convenience.  The Labels components consist of:

• ExpressLabels - use this to generate shipping labels for Express Mail.
• ConfirmationLabels - use this to generate shipping labels for other mail domestic service types.
• CustomsLabels - use this to generate shipping labels for APO/FPO packages.
• InternationalLabels - use this to generate shipping labels for international mail services.
• ReturnLabels - use this to generate an electronic merchandise return label, for use by the customer to return packages to the merchant without postage.

For shipping inside the US, ExpressLabels and ConfirmationLabels are the most commonly used.  For this example I'll use the ConfirmationLabels component which can generate shipping labels for Priority Mail, First Class Mail, Parcel Post, Bound Printer Matter, Media Mail, and Library Mail.

ConfirmationLabels1.UserId = username; 
ConfirmationLabels1.Password = password; 
ConfirmationLabels1.Server = "https://secure.shippingapis.com/ShippingAPI.dll"; 
ConfirmationLabels1.Config ("Certify=true"); 
ConfirmationLabels1.FromName = "John Smith"; 
ConfirmationLabels1.FromAddress2 = "475 L'Enfant Plaza, SW"; 
ConfirmationLabels1.FromCity = "Washington"; 
ConfirmationLabels1.FromState = "DC"; 
ConfirmationLabels1.FromZipCode = "20260"; 
ConfirmationLabels1.ToName = "Jane Smith"; 
ConfirmationLabels1.ToAddress2 = "8 Wildwood Drive"; 
ConfirmationLabels1.ToCity = "Old Lyme"; 
ConfirmationLabels1.ToState = "CT"; 
ConfirmationLabels1.WeightInOunces = 2; 
ConfirmationLabels1.ServiceType = stPriority; //0, Priority Mail 
ConfirmationLabels1.ImageType = stTif; //1, TIF file 
ConfirmationLabels1.ShippingLabelFile = "delivery_confirm.tif"; 
ConfirmationLabels1.GetDeliveryConfirmationLabel(); 
//I could also use the GetSignatureConfirmationLabel() method to generate a 
//label that will require a signature upon delivery

After the call to GetDeliveryConfirmationLabel, you'll have a file called delivery_confirm.tif that you can print, that looks something like the one pictured at right.  Affix this label to your package along with postage and it is ready to go. 

To see an example of a label generated by GetSignatureConfirmationLabel(), click here.

4.  Provide the customer with a shipment tracking number.

The Labels component that you use in step 3 will provide you with a tracking number automatically.  The ConfirmationLabels, ExpressLabels, InternationalLabels, and ReturnLabels components all have a TrackingNumber property where this information is provided.  The CustomsLabels (which again should only be used for APO/FPO deliveries or pre-paid labels) component contains a BarcodeNumber property used for tracking.

With this tracking number you can use the TrackAndConfirm component of IBiz USPS to retrieve information about the status of the shipment.  Certainly as far as the customer is concerned, they can just be directed to visit the USPS website and do their shipment tracking there.  But the TrackAndConfirm component would be particularly useful to the merchant for automatically confirming delivery of all packages sent.  Here is an example using the test server and a working test tracking number:

TrackAndConfirm1.Server = "http://testing.shippingapis.com/ShippingAPITest.dll"; //test server 
TrackAndConfirm1.UserId = username; 
TrackAndConfirm1.Password = password; 
TrackAndConfirm1.GetDetailedTrackingInfo("EJ958083578US"); 
//here I could also use the GetTrackingInfo() method, which gets a textual description 

5.  Schedule a mail carrier to pick up the package.

Now that the order process is complete, its time (hopefully) to actually ship the product to the customer.  To do this, you can walk down to the post office with the package, or you can save yourself some time and automatically schedule a mail carrier to come and pick up the package from your door.  To do this, use the CarrierPickup component to submit the package details and schedule a pickup.

First, check for the soonest available pickup date:

//This is the test server. Please note that the test requests are pre-scripted 
//so modified requests may be rejected by the test server 
CarrierPickup1.Server = "https://secure.shippingapis.com/ShippingAPITest.dll"; 
CarrierPickup1.UserId = username; 
CarrierPickup1.Password = password; 
CarrierPickup1.FirmName = "ABC Corp."; 
CarrierPickup1.SuiteOrApartment = "Suite 777"; 
CarrierPickup1.Address = "1390 Market Street"; 
CarrierPickup1.City = "Houston"; 
CarrierPickup1.State = "TX"; 
CarrierPickup1.ZipCode = "77058"; 
CarrierPickup1.Zip4 = "1234"; 
CarrierPickup1.PickupAvailability();

After calling the PickupAvailability method, the DayOfWeek and Date properties of the component will be populated with the date of the soonest available pickup date.  If carrier pickup services are not supported for the merchant address, you'll have to visit the post office in person.

Now you can call the SchedulePickup method to go ahead and schedule a carrier pickup.  To do this, simply call the SchedulePickup() method.  You'll be required to first set some properties about the person requesting pickup and the package itself.  The example below will work with the test server (note: this is the USPS "canned" test data so if you change it the test will no longer work).

//This is the test server. Please note that the test requests are pre-scripted 
//so modified requests may be rejected by the test server 
CarrierPickup1.Server = "https://secure.shippingapis.com/ShippingAPITest.dll"; 
CarrierPickup1.UserId = username; 
CarrierPickup1.Password = password; 
CarrierPickup1.FirmName = "ABC Corp."; 
CarrierPickup1.SuiteOrApartment = "Suite 777"; 
CarrierPickup1.Address = "1390 Market Street"; 
CarrierPickup1.City = "Houston"; 
CarrierPickup1.State = "TX"; 
CarrierPickup1.ZipCode = "77058"; 
CarrierPickup1.Zip4 = "1234"; 
CarrierPickup1.FirstName = "John"; 
CarrierPickup1.LastName = "Doe"; 
CarrierPickup1.PhoneNumber = "(555) 555-1234"; 
CarrierPickup1.PhoneExtension = "201"; 
CarrierPickup1.CountExpress = 1; //the number of packages being picked up for Express Mail 
CarrierPickup1.CountPriority = 1; //the number of packages being picked up for Priority Mail 
CarrierPickup1.CountInternational = 1; //the number of packages being picked up for International Mail 
CarrierPickup1.CountOther = 1; //other packages 
CarrierPickup1.EstimatedWeight = "14"; //pounds 
CarrierPickup1.PackageLocation = plOther; //9, other 
CarrierPickup1.SpecialInstructions = "Packages are behind the screen door."; 
CarrierPickup1.SchedulePickup();

In the above, all of the data is required as specified in order to work with the test server.  Once you have a live account and are ready to schedule a real pickup, change the Server URL to the production URL and specify only those properties that are required or that you need.  For a list of required pickup scheduling properties please see the IBiz USPS documentation of the SchedulePickup method.

The CarrierPickup component also gives you the means to inquire as to the status of a pickup, change a previously scheduled pickup, or cancel a previously scheduled pickup.

6.  Give the package to the carrier.

This is the easy part and requires no explanation.  All done, happy shipping!

A Note on Server URLs:

AddressInfo, ShippingTime, TrackandConfirm, and the Rates component use the following servers:
live: http://production.shippingapis.com/ShippingAPI.dll

CarrierPickup
live: https://secure.shippingapis.com/ShippingAPI.dll
test: https://secure.shippingapis.com/ShippingAPITest.dll

All of the Labels components use the following servers:
live: https://secure.shippingapis.com/ShippingAPI.dll
test: same url, but with a special "test mode" flag.  You can set this test mode flag using the IBiz USPS Integrator using the config setting "Certify=True" (ie, DomesticRates1.Config("Certify=True");).

posted @ Wednesday, June 27, 2007 12:45 PM | Filed Under [ IBiz ]