Geeks With Blogs

News

qrcode

Lance Robinson

Create Your Badge

Lance Robinson is a software engineer in Durham, Chapel Hill, Raleigh, and surrounding areas. More about Lance.

 Subscribe


Lance's TextBox » About Me » My Resume »Twitter

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.

UpdateFedEx 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.

"In the Bag", Smithsonian MagazineMail 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(); 

Verifying an address
Address Verified

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.

Rates for shipping a 1 lb, 4 oz package from 27502 to 20770

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");

Retrieving the Estimated Shipping Time... The Resulting Ship Time Estimate

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

Shipping LabelAfter 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 

Track and Confirm a Tracking Number

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
testhttps://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");).

 

Technorati Tags: , , ,
Posted on Wednesday, June 27, 2007 12:45 PM | Back to top


Comments on this post: Shipping APIs - USPS and FedEx

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Very nice article. Is the Address Verification service still offered by the USPS?

-William
Left by Address Verification on Sep 10, 2007 6:33 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
do you live in Crafton pa., by Philadelphia?
Left by l. mauser on Oct 24, 2007 12:01 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Hi there, very nice article. is there a way to print usps tracking on a label and then have third party activate the tracking and pay for it
Left by ash on Jun 22, 2008 6:31 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Hello, nice article. is there a way to print usps tracking on a label and then have third party activate the tracking and pay for it
Left by convert inches to cm on Jul 01, 2009 10:30 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
You mention printing ConfirmationLabels, but those don't actually include the postage, right? It prints a nice label, but you then have to affix stamps or go to the Post Office to get them to print out exact postage? I've always found that to be the challenge with the USPS API, unless I've misunderstood something...
Left by security for apartments on Sep 30, 2009 2:15 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Thats right: "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."

We are about to partner with a postage solution provider, so our next version (due out later this year) will allow you to print the postage as well.
Left by Lance Robinson on Oct 01, 2009 2:10 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Ah, sorry, missed that line about needing to affix postage. Yep, that's the problem I've always seen with the USPS API. Working with a postage solution provider does seem to be the way to go. Good luck with the new version. It would be great to see a similar tutorial for integrating with them, but I think they're pretty closed about that stuff and don't let you post it publicly...
Left by apartment alarm on Oct 01, 2009 2:41 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Oh, no doubt I'll be posting instructions. :)
Left by Lance Robinson on Oct 01, 2009 3:08 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
I had the same issue when I made my own program to integrate with magento commerce. You could print the label, but what about postage? And every solution I've found required an additional fee to print the postage for you.

So what did I do? Make a program that logs into their click and ship website for you and fills in all the necessary forms, payment info, ect.

Not as elegant but works like a charm. USPS really needs to get their stuff together and offer a way to pay for shipping via their API.
Left by Travis on Apr 16, 2010 12:05 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Nice little walk through. This is going to be very helpful so I'll bookmark it. Thanks
Left by Tony on Dec 14, 2010 1:42 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Hi, any update on partnership with postage provider? I'm looking for an API that I can do the full process: estimate, print, pay, track.

Thanks,
Curtis
Left by Curtis on Dec 19, 2010 11:08 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Howdy, good article. is there a way to print usps tracking on a label and then have third party activate the monitoring and pay for it
Left by agginv on Jan 04, 2011 8:30 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Very nice article. Its very useful to all ...
Left by yoursguna@gmail.com on Jan 10, 2011 4:01 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
nice article
Left by praveen on Feb 09, 2011 5:39 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Just a quick shout out that our address verification service is now FREE for all nonprofits and schools. I'm excited that we can now help a lot more groups with our service.

I work for an address verification company called SmartyStreets (http://www.smartystreets.com)
Left by Jeffrey Duncan on Oct 12, 2011 5:40 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Nice article indeed.. A step by step approach to how to have APS mail tracking...
Left by Caitlin Laura on Jun 21, 2012 1:09 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
If you are looking for an easy way to interact with the USPS API, try Postmaster: https://www.postmaster.io
Left by Miles on Feb 21, 2013 7:40 PM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
I want to integrate USPS. I want to generate Shipping Label Image. I am getting response from Server. What necessary Tag I will use at time of Ship accept.
If any document is avalable, Please send on my email id.
Left by Rakesh Kumar on Mar 16, 2013 8:06 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
EasyPost is easy to integrate and will save you the headaches of dealing with the USPS APIs
Left by Jarrett on Mar 29, 2013 2:07 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Nice article.Please help me which API can intercept package before delivered?My email is kangsoft@gmail.com.thks.
Left by Backwind on Aug 29, 2013 12:57 AM

# re: Shipping APIs - USPS and FedEx
Requesting Gravatar...
Nice article. Anyone know how to test electronic merchandise return API? I am trying to generate a PDF return label that can be emailed to our customers, but no matter what server/dll combo I use it rejects it. Of course the USPS Web Tools documentation is silent on it, and their tech support isn't much better.
Left by Art Stewart on Sep 25, 2013 12:59 PM

Your comment:
 (will show your gravatar)


Copyright © Lance Robinson | Powered by: GeeksWithBlogs.net