Getting Started with Shipping Integrator (Stamps.com)

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. This article focuses on Stamps.com which will allow your application to get USPS shipping costs, verify addresses, generate a shipping label and check the tracking status of packages that you or your users have shipped. Stamps.com supports all major domestic and international USPS services including First Class Mail, Priority Mail, Express Mail, Media Mail, and Parcel Post. Shipping Integrator includes the following components:

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


 

Getting Started

Registration with Stamps.com

If you want to use the Stamps.com service you must first register with Stamps.com. Visit http://developer.stamps.com/developer/register/ to sign up for an account.

You will then need to obtain a Stamps.com Integration Id. To get an Integration Id please contact your Stamps.com contact or Stamps.com customer support team at sws‐support@stamps.com.

Connecting to Stamps.com

After signing up for Stamps.com's services you will be provided with an Username, Password, Integration Id, and URL to which you can submit requests.

Stamps.com test environment is a complete replica of the production (live) environment and will enable you to develop your application without incurring any costs in terms of paying for the postage or subscription fees to Stamps.com.

Once you have completed your integration and meet certain basic requirements your Integration Is will be approved for migration to the Production environment. At this point you will be provided a production URL.

Test Server: https://swsim.testing.stamps.com/swsim/SwsimV45.asmx

Production Server: To be provided by Stamps.com.

Note: "Certify=True" configuration setting is required in order to generate test labels.

Uspsship ship = new Uspsship();

ship.Config("Certify=True");
.............

Stamps.com use case.

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 verify it with Stamps.com.
  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 you can implement each of these tasks:

1. Get the customer's shipping address and verify it with Stamps.com.

After you get the customers shipping address, you need to verify that address with Stamps.com. Stamps.com requires you to verify the address for all domestic shipments. Addresses cannot be verified for international shipments but destination country can be verified. Please ensure that you use a country name from the accepted list published here ‐ http://pe.usps.com/text/imm/immctry.htm. Once you have the destination address call ValidateAddress method, this will verify whether the address is valid and also make formatting changes to meet USPS addressing standard.

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 an address:

Sending a request.

Uspsaddress uspsaddress1 = new Uspsaddress();

//Set PostageProvider to 2 for Stamps.com
uspsaddress1.Config("PostageProvider=2");

//This is your Stamps.com Account Username
uspsaddress1.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
uspsaddress1.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
uspsaddress1.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
uspsaddress1.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

//This is receipient's full name required by Stamps.com
uspsaddress1.Config("FullName=Geoff Anton");

uspsaddress1.Address.Address1 = "600 Market";
uspsaddress1.Address.City = "Chapel Hill";
uspsaddress1.Address.State = "NC";
uspsaddress1.Address.ZipCode = "27516";
uspsaddress1.Company = "/n software";

uspsaddress1.ValidateAddress();

After you call ValidateAddress method the first thing to do is check the AddressMatch configuration setting that is returned. This is a Boolean value that is True if an exact match was found. If AddressMatch is False, check to see if the CityStateZipOK configuration setting is True. If this is True that means the street address provided could not be verified but the city, state and the zip match each other. The correct address may also be returned in the Stamps.com response and is available by logging the Matches property collection. In this case, you can continue to generate a label for this address but it is probably worth informing the user that the street address could not be verified. If both these configuration settings are False then you should flag an error as Stamps.com will not allow you to proceed in generating a label.

Parsing the response.

uspsaddress1.ValidateAddress();

Console.WriteLine(uspsaddress1.Config("AddressMatch"));
Console.WriteLine(uspsaddress1.Config("CityStateZipOK"));
//Whether the address is a PO Box.
Console.WriteLine(uspsaddress1.Config("IsPOBox"));
//Whether the address is of a business, residential or unknown type
Console.WriteLine(uspsaddress1.Config("ResidentialDeliveryIndicator"));

for (int i = 0; i < uspsaddress1.Matches.Count; i++)
{
    Console.WriteLine(uspsaddress1.Matches[i].Address1);
    Console.WriteLine(uspsaddress1.Matches[i].Address2);
    Console.WriteLine(uspsaddress1.Matches[i].City);
    Console.WriteLine(uspsaddress1.Matches[i].State);
    Console.WriteLine(uspsaddress1.Matches[i].ZipCode);
}

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 a list of services available to the user, using the USPSRates component.

To show the users what shipping options and costs are available to them you will need to call GetRates

Sending a request.

Uspsrates rates = new Uspsrates();

//Set PostageProvider to ppStamps for Stamps.com
rates.PostageProvider = UspsratesPostageProviders.ppStamps;

//This is your Stamps.com Account Username
rates.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
rates.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
rates.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
rates.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

String shipDate = DateTime.Now.ToString("yyyy-MM-dd");
//This is the date package will be mailed and is required by Stamps.com.
rates.Config("ShipDate=" + shipDate);

rates.SenderAddress.ZipCode = "27713";
rates.RecipientAddress.ZipCode = "27516";

rates.Packages.Add(new PackageDetail());
rates.Packages[0].Weight = "10 lbs 5 oz";
rates.Packages[0].Size = TPackages.psLarge;
rates.Packages[0].Width = 10;
rates.Packages[0].Length = 10;
rates.Packages[0].Height = 10;
rates.Packages[0].PackagingType = TPackagingTypes.ptFlatRateBox;

rates.Machinable = false;

rates.RequestedService = ServiceTypes.stUnspecified;

rates.GetRates();

The only required field for GetRates is ShipDate, but consider passing the From and To Zips at a minimum. When calling GetRates keep in mind that if you specify very few values in the request you will get a large number of rates and services returned in the response. It is best to provide as much information as possible when calling GetRates. E.g., if you know that the user wants to ship a Flat Rate box with PRiority Mail, then set this in the PackageType field and PriorityMail in the ServiceTypes field, this will limit the response to exactly what your user is looking for.

Parsing the response.

rates.GetRates();

Console.WriteLine("Postal Zone : " + rates.PostalZone);

for (int i = 0; i < rates.Services.Count; i++)
{
    Console.WriteLine("Service Type : " + rates.Services[i].ServiceTypeDescription);
    Console.WriteLine("Total Net Charge : " + rates.Services[i].ListNetCharge);
    Console.WriteLine("Rate Zone : " + rates.Services[i].RateZone);
}

AddOns.

AddOns are special services such as Signature Confirmation, Hidden Postage, Insurance, Registered Mail, etc... Available AddOns can vary based on the service type that the user chooses. Dealing with AddOns can be tricky as USPS requires that certain AddOns to be included when shipping with certain service types. Other AddOns can be optional but may carry an additional cost that you will need to inform the user.

Stamps.com returns all AddOns for each Service when calling GetRates.

Parsing AddOns from the response.

rates.GetRates();

for (int i = 0; i < rates.Services.Count; i++)
{
    rates.Config("ServiceIndex=" + i); //Setting the Service Index
    int count = Convert.ToInt32(rates.Config("AddOnCount")); //Total number of AddOns.
    for (int j = 0; j < count; j++)
    {
        Console.WriteLine("AddOn Type : " + rates.Config("AddOnType[" + j + "]"));
        Console.WriteLine("AddOn Description : " + rates.Config("AddOnTypeDescription[" + j + "]"));
        Console.WriteLine("AddOn Amount : " + rates.Config("AddOnAmount[" + j + "]"));
        //Console.WriteLine("AddOn Aggregate : " + rates.Config("AddOnAggregate[" + j + "]"));
    }
}

Note: You can also get the raw XML returned by Stamps.com for each AddOn by logging the AddOnAggregate configuration settings (commented out for simplicity in the sample code above).

Rates depend on location (from and to), size and dimensions, weight, container (envelope, box, etc), and service type. Package length, width, and height are required for proper rating for all package sizes.

ServiceType is not required when calling GetRates method and if not set Stamps.com will return all available service types.

Available service types:

  • First Class
  • Media
  • Parcel Post
  • Priority
  • Express
  • Express Mail International
  • Priority Mail International
  • First Class Mail International
  • Critical Mail
  • Parcel Select
  • Library
The ServiceType property has an "stUnspecified" setting that will tell the component to retrieve rates for all available service types.

When PackageType is set to ptYourPackaging, Package Size will be used to determine the PackageType and setting it to Package, Large Package or Oversize Package. If none of these properties are set then Stamps.com will return all rates for all of the possible PackageType for the given ServiceType.

Available package types:

  • Large Envelope
  • Flat Rate Envelope
  • Flat Rate Box
  • Small Flat Rate Box
  • Medium Flat Rate Box
  • Large Flat Rate Box
  • Regional Rate Box A
  • Regional Rate Box B
  • Regional Rate Box C
  • Flat Rate Legal Envelope
  • Postcards
  • Letter
  • Flat Rate Padded Envelope
  • Your Packaging

To get the shipping time, after calling GetRates method, all you need to do is check the DeliveryDay field of the Services property collection:

Parsing DeliveryDay from the response.

rates.GetRates();

for (int i = 0; i < rates.Services.Count; i++)
{
    Console.WriteLine("It will take approximately " + rates.Services[i].DeliveryDay + " days to ship.");
}

Note: If DeliveryDay is blank, it means that no delivery time estimates are available, otherwise a string will be returned in the format "n-m", n being minimum number of days, m being maximum number of days.

3. Print a shipping label for the package.

This section gives you a basic idea on how the USPSShip and USPSShipIntl components can be used to generate basic domestic and international shipping labels. Labels can be generated in PNG (default for domestic shipments), JPG, PDF (default for international shipments), GIF, EPL, and ZPL for your printing convenience.

Sending a request for domestic shipment.

Uspsship ship = new Uspsship();

ship.Config("Certify=true"); //Required only during testing.

//Set PostageProvider to ppStamps for Stamps.com
ship.PostageProvider = UspsratesPostageProviders.ppStamps;

//This is your Stamps.com Account Username
ship.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
ship.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
ship.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
ship.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

// Sender Information 
ship.SenderContact.FirstName = "John";
ship.SenderContact.LastName = "Smith";
ship.SenderContact.Company = "CDATA Software";
ship.SenderContact.Phone = "9195447070";
ship.SenderAddress.Address1 = "5007 Southpark Drive";
ship.SenderAddress.Address2 = "Suite 240";
ship.SenderAddress.City = "Durham";
ship.SenderAddress.State = "NC";
ship.SenderAddress.ZipCode = "27713";

//Recipient Information
ship.RecipientContact.Company = "/n Software";
ship.RecipientContact.FirstName = "Jane";
ship.RecipientContact.LastName = "Smith";
ship.RecipientContact.Phone = "9876543210";
ship.RecipientAddress.Address1 = "600 Market St.";
ship.RecipientAddress.City = "Chapel Hill";
ship.RecipientAddress.State = "NC";
ship.RecipientAddress.ZipCode = "27516";

ship.ServiceType = ServiceTypes.stUSPSPriority;
ship.ShipDate = DateTime.Now.ToString("yyyy-MM-dd"); //Required by Stamps.com
ship.LabelImageType = UspsshipLabelImageTypes.sitPNG;

ship.Packages.Add(new PackageDetail());
ship.Packages[0].Weight = "10 lbs 5 oz";
ship.Packages[0].Size = TPackages.psLarge;
ship.Packages[0].Width = 10;
ship.Packages[0].Length = 10;
ship.Packages[0].Height = 10;
ship.Packages[0].PackagingType = TPackagingTypes.ptFlatRateBox;
ship.Packages[0].ShippingLabelFile = "C:\\StampsDomesticLabel.png"; //Valid Path

ship.GetPackageLabel();

If ShippingLabelFile field is set, like in the example above, a label will be saved on disc.

If LabelImageType is set to "sitNone", Stamps.com will return a URL which links to an image of the shipping label that you requested

Parsing Label URL from the response.

.................
ship.LabelImageType = UspsshipLabelImageTypes.sitNone;

ship.GetPackageLabel();

Console.WriteLine(ship.Config("PackageLabelUrl"));

For shipment special services like Delivery Confirmation, Insurance, COD, etc.. You will need to set the AddOnTypes configuration setting before calling GetPackageLabel method. This configuration setting accepts multiple, comma separated,AddOns.

Requesting Special AddOns

.................
//Request USPS Delivery Confirmation and USPS Special Handling services
ship.Config("AddOnTypes=US-A-DC,US-A-SH");

ship.GetPackageLabel();

Note: For a list of all AddOns available and its corresponding rate for the each Service Type refer to Parsing AddOns from the response section above.

The process of generating labels for international shipments is the same but a few more properties and configuration settings like DeclaredValue, Commodities, StandardizeAddress, etc.. must be set.

Depending on the USPS service selected there are two different types of customs forms that can be generated – the 2976 or the 2976‐A. The 2976 is the short form single page layout. The 2976‐A is a full form 3 page layout including instructions. Stamps.com will automatically generate the correct customs form and will return a label with postage and customs form combined.

Sending a request for international shipment.

Uspsshipintl ship = new Uspsshipintl();

ship.Config("Certify=true"); //Required only during testing.

//Set PostageProvider to ppStamps for Stamps.com
ship.PostageProvider = UspsshipintlPostageProviders.ppStamps;

//This is your Stamps.com Account User name
ship.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
ship.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
ship.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
ship.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

// Sender Information 
ship.SenderContact.FirstName = "John";
ship.SenderContact.LastName = "Smith";
ship.SenderContact.Company = "/n Software";
ship.SenderContact.Phone = "9195447070";
ship.SenderAddress.Address1 = "5007 Southpark Drive";
ship.SenderAddress.Address2 = "Suite 240";
ship.SenderAddress.City = "Durham";
ship.SenderAddress.State = "NC";
ship.SenderAddress.ZipCode = "27713";

//Recipient Information
ship.RecipientContact.FirstName = "Jean-Pierre";
ship.RecipientContact.LastName = "Raffarin";
ship.RecipientContact.Company = "XYZ Paris";
ship.RecipientContact.Phone = "1807332021";
ship.RecipientContact.Fax = "1807332027";
ship.RecipientContact.Email = "JPR@DLEURO.COM";
ship.RecipientAddress.Address1 = "Service Recruitment G A";
ship.RecipientAddress.Address2 = "Bat. Merlin";
ship.RecipientAddress.City = "Paris";
ship.RecipientAddress.State = "Cedex 4";
ship.RecipientAddress.CountryCode = "FR";
ship.RecipientAddress.ZipCode = "";

ship.Config("DeclaredValue=1000"); //Required by Stamps.com
ship.ShipDate = DateTime.Now.AddDays(2).ToString("yyyy-MM-dd"); //Required by Stamps.com

ship.Commodities.Add(new CommodityDetail());
ship.Commodities[0].Description = "Stockholders Report Q1";
ship.Commodities[0].Quantity = 1;
ship.Commodities[0].Value = "15.00";
ship.Commodities[0].Manufacturer = "United States";
ship.Commodities[0].Weight = "2 oz";

ship.Packages.Add(new PackageDetail());
ship.Packages[0].Weight = "10 lbs 5 oz";
ship.Packages[0].Size = TPackages.psLarge;
ship.Packages[0].Width = 10;
ship.Packages[0].Length = 10;
ship.Packages[0].Height = 10;
ship.Packages[0].PackagingType = TPackagingTypes.ptLargeFlatRateBox;
ship.Packages[0].ShippingLabelFile = "C:\\StampsInternationalLabel.pdf"; //Valid Path

ship.LabelImageType = UspsshipintlLabelImageTypes.sitPDF;
ship.MailingLocation = "12345";
ship.Contents = UspsshipintlContents.ctDocuments;
ship.ServiceType = ServiceTypes.stUSPSPriorityMailInternational;

ship.GetPackageLabel();

Note that by default international labels are returned as PDFs. This is because the 3‐page 2976‐A can be concatenated into a single 3‐page PDF document.

4. Provide the customer with a shipment tracking number.

Once you've generated a shipping label you've pretty much completed the basic Stamps.com integration. There are a number of features you will still need to provide but the process gets easier from here on

The USPSShip component that you use in step 3 will provide you with a tracking number automatically You can use the TrackingNumber field of the Packages collection to obtain this information. For example:

Getting the tracking number after generating the label.

..........
ship.GetPackageLabel();

Console.WriteLine(ship.Packages[0].TrackingNumber);

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/Stamps.com 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:

Sending a request.

Uspstrack track = new Uspstrack();

//Set PostageProvider to ppStamps for Stamps.com
track.PostageProvider = UspstrackPostageProviders.ppStamps;

//This is your Stamps.com Account Username
track.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
track.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
track.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
track.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

track.TrackShipment("9455111899562857606067"); // Stamps.com Tracking Number

Note: Tracking is not available for First Class Domestic Flats or all First Class International mail and is optional for First Class Domestic Packages.

Parsing the response.

track.TrackShipment("9455111899562857606067"); // Stamps.com Tracking Number

for (int i = 0; i < track.TrackEvents.Count; i++)
{
    Console.WriteLine(track.TrackEvents[i].Time);
    Console.WriteLine(track.TrackEvents[i].Date);
    Console.WriteLine(track.TrackEvents[i].Status);
    Console.WriteLine(track.TrackEvents[i].City);
    Console.WriteLine(track.TrackEvents[i].State);
    Console.WriteLine(track.TrackEvents[i].ZipCode);
    Console.WriteLine(track.TrackEvents[i].CountryCode);
    Console.WriteLine(track.TrackEvents[i].Other);
}

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.

Note: To do so the user must have shipped at least one domestic Priority or Express Mail package or any international package. You will need to provide the name and address where the packages are to be picked up and the number of Priority, Express and international packages to be picked up. If the request is successful you will receive a date and time of pickup along with a confirmation number.

Sending a Package Pickup request.

Uspsship ship = new Uspsship();

ship.Config("Certify=true"); //Required only during testing.

//Set PostageProvider to ppStamps for Stamps.com
ship.PostageProvider = UspsratesPostageProviders.ppStamps;

//This is your Stamps.com Account Username
ship.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
ship.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
ship.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
ship.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

//Sender Information
ship.SenderContact.FirstName = "John";
ship.SenderContact.LastName = "Smith";
ship.SenderContact.Company = "n Software";
ship.SenderAddress.Address1 = "5007 Southpark Drive";
ship.SenderAddress.Address2 = "Suite 240";
ship.SenderAddress.City = "Durham";
ship.SenderAddress.State = "NC";
ship.SenderAddress.ZipCode = "27713";
ship.SenderContact.Phone = "9195447070";

ship.CountExpress = 1;
ship.CountInternational = 1;
ship.CountOther = 1;
ship.CountPriority = 1;
ship.TotalWeight = 14;

ship.PackageLocation = UspsshipPackageLocations.plOther;
ship.Config("SpecialInstructions=Packages are behind the screen door.");

string ConfirmationNumber = ship.SchedulePickup();

After calling the SchedulePickup 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. The Confirmation Number will be returned after a successful request.

Parsing Package Pickup response.

string ConfirmationNumber = ship.SchedulePickup();

Console.WriteLine(ConfirmationNumber);
Console.WriteLine(ship.ShipDate);

In the above example, the data provided, may not 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. For a list of required pickup scheduling properties please see the USPSShip documentation of the SchedulePickup method.

6. Give the package to the carrier.

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

Managing your Stamps.com Account

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

  • GetAccountstatus - Get the status of your account
  • Recredit - Used to buy postage.
  • GetPurchaseStatus - Check purchase status.
  • Refund - Request a refund for a shipment.
  • ChangePassPhrase - Change the password for your account.

Buying Stamps.com postage.

Apart from the amount of postage the user wishes to purchase you should also set the ControlTotal configuration setting. This is the amount of postage that the user has consumed over the lifetime of the account. Sending ControlTotal lets the server know if you have the correct postage balance when buying postage. If you do not then it is possible that the postage balance was changed through other means (the user could have logged in through another integrated application to purchase or print postage). Initially it is returned by Stamps.com after calling GetAccountStatus. Thereafter, you can track the ControlTotal by adding the postage consumed with each print to the previous ControlTotal.

Sending a request to get GetAccountstatus and ControlTotal.

Uspsmgr mgr = new Uspsmgr();

//Set PostageProvider to 2 for Stamps.com
mgr.Config("PostageProvider=2");

//This is your Stamps.com Account Username
mgr.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
mgr.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
mgr.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
mgr.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

mgr.GetAccountStatus();

Parsing the response.

mgr.GetAccountStatus();

Console.WriteLine(mgr.PostageBalance);
Console.WriteLine(mgr.Config("ControlTotal"));

Note: For any other fields returned in the response after calling GetAccountStatus you can use the XPath configuration setting to parse it. For example:

Using XPath to parse additional fields.

mgr.GetAccountStatus();

Console.WriteLine("My Customer Id : " + mgr.Config("XPath=/Envelope/Body/GetAccountInfoResponse/AccountInfo/CustomerID"));

The above XPath example will log the Customer Id returned by Stamps.com after calling GetAccountstatus. For more information about the XPath and RawResponse configuration settings please refer to the help file.

After getting the ControlTotal from calling GetAccountstatus method you may now use this value to purchase postage.

Sending a request for buying postage.

Uspsmgr mgr = new Uspsmgr();

//Set PostageProvider to 2 for Stamps.com
mgr.Config("PostageProvider=2");

//This is your Stamps.com Account Username
mgr.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
mgr.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
mgr.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
mgr.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

//Required by Stamps.com when purchasing postage.
mgr.Config("ControlTotal=50.00");

mgr.Recredit("10.00");

Parsing response.

mgr.Recredit("10.00");

Console.WriteLine(mgr.Config("PurchaseStatus"));
Console.WriteLine(mgr.PostageBalance);
Console.WriteLine(mgr.Config("TransactionID"));
Console.WriteLine(mgr.Config("ControlTotal"));

The first thing to do after calling Recredit is to check the PurchaseStatus. This can be Success, Pending, Processing or Rejected.

  • Success: If the PurchaseStatus configuration setting is Success then you can inform the user of the successful purchase. The PostageBalance property is the new balance in the user's account.
  • Pending, Processing: If the status is either Pending or Processing then you'll have to call GetPurchaseStatus configuration setting to see if the purchase went through successfully. Use the TransactionID returned from calling GetPurchaseStatus.
  • Rejected: If the status is Rejected then check the exception to see why the purchase was rejected. If it was because of a stale (incorrect) ControlTotal then show the user the new PostageBalance and check to see if they would like to continue purchasing postage. If it was rejected for any other reason you should inform the user.

Checking PurchaseStatus (this will happen if the original purchase status was pending or processing).

Uspsmgr mgr = new Uspsmgr();

//Set PostageProvider to 2 for Stamps.com
mgr.Config("PostageProvider=2");

//This is your Stamps.com Account Username
mgr.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
mgr.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
mgr.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
mgr.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

//Required by Stamps.com when purchasing postage.
mgr.Config("ControlTotal=50.00");

mgr.Config("TransactionID=69451031");

mgr.Config("GetPurchaseStatus");

Parsing response.

mgr.Config("GetPurchaseStatus");

Console.WriteLine(mgr.Config("PurchaseStatus"));
Console.WriteLine(mgr.PostageBalance);
Console.WriteLine(mgr.Config("ControlTotal"));

Refunds.

Users can request a refund for shipping labels that they are not going to use. The Refund method provides a way to request a refund for a shipment. For stamps.com the identifier will be the StampsTxId. StampsTxId is returned by USPSShip or USPSShipIntl component after calling GetPackageLabel method.

Parsing StampsTxId after calling GetPackageLabel using USPSShip or USPSShipIntl component.

ship.GetPackageLabel();
 
Console.WriteLine(ship.Config("StampsTxId"));

Using the StampsTxId obtained after generating the label you can now try to refund this transaction.

Sending a refund request.

Uspsmgr mgr = new Uspsmgr();

//Set PostageProvider to 2 for Stamps.com
mgr.Config("PostageProvider=2");

//This is your Stamps.com Account Username
mgr.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
mgr.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
mgr.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
mgr.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

// This is the StampsTxId returned by USPSShip or USPSShipIntl component after calling GetPackageLabel method.
mgr.Refund("49898f08-1ce4-42e1-8af0-b429481fc8f3", 0);

Note: If there are no errors thrown by the component, it means that the refund was successful. Stamps.com does not return a refund status.

Changing your account password.

To change your account password you will need to call the ChangePassPhrase method and pass the value of your new password. For instance:

Uspsmgr mgr = new Uspsmgr();

//Set PostageProvider to 2 for Stamps.com
mgr.Config("PostageProvider=2");

//This is your Stamps.com Account Username
mgr.USPSAccount.UserId = "YourUsername";

//This is your Stamps.com Account Password
mgr.USPSAccount.Password = "YourPassword";

//This is your Stamps.com Integration Id
mgr.USPSAccount.AccountNumber = "YourIntegrationId";

//This is Stamps.com Test Server URL
mgr.USPSAccount.Server = "https://swsim.testing.stamps.com/swsim/SwsimV45.asmx";

mgr.ChangePassPhrase("NewPassword");

Note: If there are no errors thrown by the component, it means that password was successful changed. Stamps.com does not return a confirmation.

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 support@nsoftware.com.


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