US Postal Service Integrator

Requirements: /n software Shipping Integrator

Introduction

Shipping Integrator is a toolkit that enables software developers to quickly and easily incorporate USPS shipping capabilities into their software applications and websites.  In this latest release we have also added support for services offered by Endicia which will allow you to obtain labels with postage included. If you use the USPS services, you must affix postage to the generated labels before shipping. Choosing the postage provider to use is covered later in this tutorial. ShippingIntegrator includes the following components:

  • USPSAddress component: Validate or lookup recipient addresses by checking street address, city, state, and zip code.
  • USPSMgr component: Provides a way to perform account management operations.
  • USPSRates component: Retrieves courtesy rate quotes for a specific account and service types.
  • USPSShip Generates complete USPS domestic shipping labels, including addresses and barcodes.
  • USPSShipIntl component: Generates complete USPS international shipping labels, including addresses and barcodes, as well as obtaining CN22 and CP72 forms.
  • USPSTrack component: Provides tracking information for packages.


 

Getting Started

Creating an Endicia Account

To use the Endicia service you must first create an account. Visit https://account.endicia.com/?referredBy=lsft to open an account.

Specify your account credentials in the USPSAccount properties of the component during development.

Note: If you are developing a solution that will be sold to other companies they will be required to open their own account. Your customers should be directed to the above URL to sign up for their own account, and your application should support a way for the customer to provide their account information.

Registration with USPS

Before you can use these components to communicate with the US Postal Service, you must register with USPS for access to their WebTools APIs. Online registration is free and provides developers with a unique username that must be used when accessing shipping services. To register for your free username visit: http://www.uspswebtools.com/registration/. Also more information on USPS's online tools can be found here: http://www.usps.com/webtools/.

Connecting to Endicia

After signing up for Endicia's services you will be provided with an Account Number, Password, and URL to which you can submit requests.

Managing your Endicia Account

The USPSMgr component provides access to account management functionality for Endicia. Using the methods and properties exposed here will allow you to programmatically manage accounts. Below is a list of currently supported operations.

  • Recredit - Used to buy Postage.
  • Refund - Request a refund for a shipment.
  • ChangePassPhrase - Change the password for an account.
  • GetAccountstatus - Get the status of an account
  • 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 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 input data.  Note:  if you plan to use delivery/signature confirmation or merchandise return service, 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".

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

    1. Get the customer's shipping address (and optionally verify it with USPS).
    2. Allow the customer to choose what type of shipping to use, and 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 (and 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 USPSAddress component allows you to verify a complete address, lookup a zip code of a city/state, and lookup the city/state of a zip code method).  Here is an example of using the USPSAddress component to verify ("standardize") an address:

      Uspsaddress uspsaddress1 = new Uspsaddress();
      uspsaddress1.USPSAccount.Server = 
        "http://testing.shippingapis.com/ShippingAPITest.dll";
      uspsaddress1.USPSAccount.UserId = userId;
      uspsaddress1.USPSAccount.Password = password;
    
      uspsaddress1.Address.Address1 = "6406 Ivy Lane";
      uspsaddress1.Address.City = "Greenbelt";
      uspsaddress1.Address.State = "MD";
      uspsaddress1.ValidateAddress();
    
      Console.WriteLine(uspsaddress1.Matches[0].Address1);
      Console.WriteLine(uspsaddress1.Matches[0].City);
      Console.WriteLine(uspsaddress1.Matches[0].State);
      Console.WriteLine(uspsaddress1.Matches[0].ZipCode);
    

      

    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 USPSRates component.

    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 to obtain rates from either USPS or Endicia:

      Uspsrates uspsrates1 = new Uspsrates();
    
      //To choose the provider set the PostageProvider property. Default is USPS (None)
      uspsrates1.PostageProvider = UspsratesPostageProviders.ppNone;
    
      if (uspsrates1.PostageProvider == UspsratesPostageProviders.ppNone) //USPS
      {
        uspsrates1.USPSAccount.Server = 
          "http://production.shippingapis.com/ShippingAPI.dll";
        uspsrates1.USPSAccount.UserId = USPSUserId;
        uspsrates1.USPSAccount.Password = USPSPassword;
      }
      else //Endicia
      {
        uspsrates1.USPSAccount.Server = EndiciaServerURL; //Provided by Endicia
        uspsrates1.USPSAccount.AccountNumber = EndiciaAccountNumber;
        uspsrates1.USPSAccount.Password = EndiciaPassword;
      }
    
      uspsrates1.SenderAddress.ZipCode = "27502";
      uspsrates1.RecipientAddress.ZipCode = "20770";
      uspsrates1.Packages.Add(new PackageDetail());
      uspsrates1.Packages[0].Length = 2;
      uspsrates1.Packages[0].Width = 2;
      uspsrates1.Packages[0].Height = 2;
      uspsrates1.Packages[0].Size = TPackages.psRegular;
    
      if (uspsrates1.PostageProvider == UspsratesPostageProviders.ppNone) //USPS
      {
        uspsrates1.Packages[0].Weight = "2 lbs 2 oz"; //Format of "N lbs N oz".
        //Return rates for all services.
        uspsrates1.RequestedService = ServiceTypes.stUnspecified; 
      }
      else //Endicia
      {
        uspsrates1.Packages[0].Weight = "2.1"; //Format of "N.N".
        //Endicia requires that you select a specific service
        uspsrates1.RequestedService = ServiceTypes.stUSPSExpress; 
      }
    
      uspsrates1.GetRates();
    
      for (int i = 0; i < uspsrates1.Services.Count; i++)
      {
        Console.WriteLine("Service and Cost: " 
          + uspsrates1.Services[i].ServiceTypeDescription 
          + "\t" + uspsrates1.Services[i].ListNetCharge);
      }

    Note that package length, width, and height are required for large packages, but it is okay to send them for all package sizes

    Rates depend on location (from and to), size and dimensions, weight, container (envelope, box, etc), and service type.  (Package length width and height are not required for the psRegular package size, but it is okay to send them. They are required for all other package sizes).

    Available service types:

  • Express
  • First Class
  • Priority
  • Parcel Post
  • Bound Printed Matter
  • Media
  • Library
  • Online
  • Global Express
  • Parcel Select
  • Critical Mail
  • Standard Mail
  • Express Mail International
  • First Class Mail International
  • Priority Mail International
  • The ServiceType property has an "all" setting that will tell the component to retrieve rates for all available service types (not applicable when using Endicia as a ServiceType must be specified there).


    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 10 lb, 5 oz package from 10022 to 20008

    To compute the shipping time, use the GetShippingTime method of the USPSRates component and simply provide the from zip, the destination zip, and the service type:

      Uspsrates uspsrates1 = new Uspsrates();
      uspsrates1.USPSAccount.UserId = USPSUserId;
      uspsrates1.USPSAccount.Password = USPSPassword;
      uspsrates1.USPSAccount.Server = 
        "http://production.shippingapis.com/ShippingAPI.dll";
          
      uspsrates1.RecipientAddress.ZipCode = "20770";
      uspsrates1.SenderAddress.ZipCode = "27502";
      uspsrates1.RequestedService = ServiceTypes.stUSPSExpress;
    
      uspsrates1.GetShippingTime();
    
      Console.WriteLine("It will take approximately " + 
        uspsrates1.Days + " days to ship.");
    

    3.  Print a shipping label for the package.

    Use one of the Ship components to generate a shipping label for your package.  The components will generate labels in TIF, PDF, or GIF formats for your printing convenience. When using Endicia available formats are GIF, JPG, PDF, ZPL, and EPL.  The Ship components consist of:

    • USPSShip - use this to generate domestic shipping labels.
    • USPSShipIntl - use this to generate shipping labels for international mail services and obtain customs forms.

    For this example I'll use the USPSShip component which can generate shipping labels for Express, Priority Mail, First Class Mail, Parcel Post, Bound Printer Matter, Media Mail, and Library Mail.

      Uspsship uspsship1 = new Uspsship();
    
      //To choose the provider set the PostageProvider property. Default is USPS (None)
      uspsship1.PostageProvider = UspsshipPostageProviders.ppEndicia;
    
      if (uspsship1.PostageProvider == UspsshipPostageProviders.ppNone) //USPS
      {
        uspsship1.Config("Certify=true"); //Test labels with the live server.
        uspsship1.USPSAccount.Server =
          "https://secure.shippingapis.com/ShippingAPI.dll";
        uspsship1.USPSAccount.UserId = USPSUserId;
        uspsship1.USPSAccount.Password = USPSPassword;
      }
      else //Endicia
      {
        uspsship1.USPSAccount.Server = EndiciaServerURL; //Provided by Endicia
        uspsship1.USPSAccount.AccountNumber = EndiciaAccountNumber;
        uspsship1.USPSAccount.Password = EndiciaPassword;
      }
    
      uspsship1.SenderContact.FirstName = "John";
      uspsship1.SenderContact.LastName = "Smith";
      uspsship1.SenderAddress.Address1 = "475 L'Enfant Plaza, SW";
      uspsship1.SenderAddress.City = "Washington";
      uspsship1.SenderAddress.State = "DC";
      uspsship1.SenderAddress.ZipCode = "20260";
    
      uspsship1.RecipientContact.FirstName = "Jane";
      uspsship1.RecipientContact.LastName = "Smith";
      uspsship1.RecipientAddress.Address1 = "8 Wildwood Drive";
      uspsship1.RecipientAddress.City = "Old Lyme";
      uspsship1.RecipientAddress.State = "CT";
      uspsship1.RecipientAddress.ZipCode = "06371";
    
      uspsship1.Packages.Add(new PackageDetail());
    
      if (uspsship1.PostageProvider == UspsshipPostageProviders.ppNone) //USPS
      {
        uspsship1.LabelImageType = UspsshipLabelImageTypes.sitTIF;
        uspsship1.Packages[0].ShippingLabelFile = "test_label.tif";
        uspsship1.Packages[0].Weight = "8 oz";
        uspsship1.LabelOption = "1";
        uspsship1.Packages[0].SignatureType = TSignatureTypes.stNoSignatureRequired;
      }
      else //Endicia
      {
        uspsship1.CustomerId = "2322"; //Required for Endicia
        uspsship1.TransactionId = "ABCDEFGH"; //Required for Endicia
        uspsship1.LabelImageType = UspsshipLabelImageTypes.sitPNG;
        uspsship1.Packages[0].ShippingLabelFile = "test_label.png";
        uspsship1.Packages[0].Weight = "2.0";
      }
    
      uspsship1.ServiceType = ServiceTypes.stUSPSPriority;
    
      uspsship1.GetPackageLabel();
      
      Console.WriteLine(uspsship1.Packages[0].TrackingNumber);
    After the call to GetPackageLabel, you'll have a file 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. 

    Shipping Label

    4.  Provide the customer with a shipment tracking number.

    The Ship component that you use in step 3 will provide you with a tracking number automatically.  As above you can use the TrackingNumber field of the Packages collection to obtain this information. 

    With this tracking number you can use the USPSTrack component 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 USPSTrack 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:

      Uspstrack uspstrack1 = new Uspstrack();
      uspstrack1.USPSAccount.UserId = USPSUserId;
      uspstrack1.USPSAccount.Password = USPSPassword;
      uspstrack1.USPSAccount.Server = 
        "http://testing.shippingapis.com/ShippingAPITest.dll";
    
      uspstrack1.TrackShipment("EJ958083578US");
    
      for (int i = 0; i < uspstrack1.TrackEvents.Count; i++)
      { 
        Console.WriteLine(uspstrack1.TrackEvents[i].Status + ": " + 
        uspstrack1.TrackEvents[i].Date + ": " + 
        uspstrack1.TrackEvents[i].City + ", " + uspstrack1.TrackEvents[i].State);
      }
    

    Track using 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 USPSShip component to submit the package details and schedule a pickup via the SchedulePickup method.

    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
      Uspsship uspsship1 = new Uspsship();
      uspsship1.USPSAccount.Server = 
        "https://secure.shippingapis.com/ShippingAPITest.dll";
      uspsship1.USPSAccount.UserId = USPSUserId;
      uspsship1.USPSAccount.Password = USPSPassword;
      uspsship1.SenderContact.Company = "ABC Corp.";
      uspsship1.SenderAddress.Address1 = "1390 Market Street";
      uspsship1.SenderAddress.Address2 = "Suite 777";
      uspsship1.SenderAddress.City = "Houston";
      uspsship1.SenderAddress.State = "TX";
      uspsship1.SenderAddress.ZipCode = "77058-1234";
      uspsship1.PickupAvailability();
    
      Console.Write(uspsship1.ShipDate);

    After calling the PickupAvailability method, the ShipDate property 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
      Uspsship uspsship1 = new Uspsship();
      uspsship1.USPSAccount.Server = "https://secure.shippingapis.com/ShippingAPITest.dll";
      uspsship1.USPSAccount.UserId = USPSUserId;
      uspsship1.USPSAccount.Password = USPSPassword;
      uspsship1.SenderContact.Company = "ABC Corp.";
      uspsship1.SenderAddress.Address1 = "1390 Market Street";
      uspsship1.SenderAddress.Address2 = "Suite 777";
      uspsship1.SenderAddress.City = "Houston";
      uspsship1.SenderAddress.State = "TX";
      uspsship1.SenderAddress.ZipCode = "77058-1234";
      uspsship1.SenderContact.FirstName = "John";
      uspsship1.SenderContact.LastName = "Doe";
      uspsship1.SenderContact.Phone = "(555) 555-1234";
      uspsship1.Config("SenderPhoneExt=201");
          
      //the number of packages being picked up for Express Mail
      uspsship1.CountExpress = 1;  
      //the number of packages being picked up for Priority Mail
      uspsship1.CountPriority = 1;     
      //the number of packages being picked up for International Mail
      uspsship1.CountInternational = 1;
      //other packages
      uspsship1.CountOther = 1;
    
      uspsship1.PackageLocation = UspsshipPackageLocations.plOther;
      uspsship1.TotalWeight = 14; //pounds
      uspsship1.Config("SpecialInstructions=Packages are behind the screen door.");
      uspsship1.SchedulePickup();
    
      Console.WriteLine(uspsship1.ShipDate);

    In the above example, 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 USPS documentation of the SchedulePickup method.

    The USPSShip 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!

    Conclusions

    This article demonstrates the ease of use of the Shipping Integrator.  In this tutorial I've gone over some of the most commonly used components and uses, however if there are any questions you have that I've not covered here please do not hesitate to contact us via the link at the top or bottom of this tutorial.

    A Note on Server URLs:

    Note: You can create test labels with the live server by setting the Certify configuration setting (i.e. USPSShip1.Config("Certify=True");).

    We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.