4D Shipping - Getting Started with Stamps

Materials:

Contents

Introduction

To work with Stamps.com use the USPS components. Whenever working with Stamps.com the PostageProvider property should be set to ppStamps. During the development phase there is a testing environment provided. Any of the USPS components can be easily configured to make requests to the testing environment while using a built-in sandbox account. To configure the component for testing set the StampsTestMode configuration setting to 1, like this example:

Uspsship ship = new Uspsship(); ship.PostageProvider = UspsshipPostageProviders.ppStamps; ship.Config("StampsTestMode=1");

When a production account has been acquired configure the component to use that account by setting USPSAccount.UserId and USPSAccount.Password. There is no need to set USPSAccount.Server, it will be set automatically.

Uspsship ship = new Uspsship(); ship.PostageProvider = UspsshipPostageProviders.ppStamps; ship.USPSAccount.UserId = "Production UserId"; ship.USPSAccount.Password = "Production Password";

Purchasing Postage

A Stamps.com account has a postage balance that can be used to purchase postage. Postage is used any time a label is generated.

The Uspsmgr component is used to purchase postage and manage accounts. To get information about an account call the GetAccountStatus method, like this example:

Uspsmgr mgr = new Uspsmgr(); // Postage provider is exposed // as a config with Uspsmgr. mgr.Config("PostageProvider=2"); mgr.Config("StampsTestMode=1"); mgr.GetAccountStatus(); string controlTotal = mgr.Config("ControlTotal"); Console.Writeline("Account Postage Balance: " + mgr.PostageBalance); Console.Writeline("Account Control Total: " + controlTotal);

The two primary pieces of account information that come back are PostageBalance and ControlTotal. The former is the current balance of postage in an account. The latter is a special value that will be required in requests to purchase postage. Purchasing postage is done with the Recredit method, like this example:

mgr.Config("ControlTotal=" + controlTotal); mgr.Recredit("100.00");

Notice that the ControlTotal from the previous example was used to make this request. This value will always need to be retrieved first by calling GetAccountStatus.

Validating an Address

It is important when shipping that a provided address is accurate. Otherwise there is always a risk that package does not get properly delivered and subsequently returned, or the worse alternative: lost. This is why it is a good idea to validate any addresses before using them. The Uspsaddress component is used to validate addresses. As much information about an possible address should be provided. Afterwards the ValidateAddress method should be called. Stamps.com’s servers will respond with a list of potential matches, contained in the Matches collection, for that address. Here is an example:

Uspsaddress addr = new Uspsaddress(); // Postage provider is exposed // as a config with Uspsaddress. addr.Config("PostageProvider=2"); addr.Config("StampsTestMode=1"); addr.Config("FullName=Steve Irwin"); addr.Address.Address1 = "101 Europa Dr."; addr.Address.City = "Chapel Thrill"; addr.Address.State = "NC"; addr.Address.ZipCode = "27516"; addr.ValidateAddress(); for (int x = 0; x < addr.Matches.Count; x++) { MatchDetail match = addr.Matches[x]; Console.WriteLine("---Match #" + x + "---\r\n" + "\r\nProposed Address:\r\n" + match.Address1 + "\r\n" + (match.Address2 != "" ? match.Address2 + "\r\n" : "") + match.City + "\r\n" + match.State + "\r\n" + match.ZipCode + "\r\n"); }

Stamps.com requires that a FullName is provided for a given address. This is set through the eponymously named configuration setting.

Rating Packages

Once there is postage available to an account the next step would be to estimate a rate for shipping a package. Rates returned from Stamps.com’s server are estimates and may not reflect the final price of sending a package. If there are any questions or disputes about the final price charged for shipping a package please get in touch with Stamps.com directly.

Uspsrates is used to rate packages and there are two ways to rate a package. The first is without selecting a specific service type. This will return a list of available services along with their rates. Here is an example:

Uspsrates rates = new Uspsrates(); rates.PostageProvider = UspsratesPostageProviders.ppStamps; rates.Config("StampsTestMode=1"); rates.Packages.Add(new PackageDetail()); rates.Packages[0].Weight = "1.1"; rates.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging; rates.SenderAddress.ZipCode = "27516"; rates.RecipientAddress.ZipCode = "28608"; rates.Config("ShipDate=" + DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")); rates.GetRates(); foreach(ServiceDetail service in rates.Services) { Console.WriteLine(service.ServiceTypeDescription + " would be delivered on " + service.DeliveryDate + " days and cost $" + service.ListNetCharge); }

The second way to rate shipping a package is to provide a specific service type to the RequestedService property before calling GetRates. Building on the last example:

rates.RequestedService = ServiceTypes.stUSPSFirstClass; rates.GetRates(); for (int x = 0; x < rates.Services.Count; x++) { rates.Config("ServiceIndex=" + x); Console.WriteLine(rates.Services[x].ServiceTypeDescription + " is available with these options: "); for (int y = 0; y < Int32.Parse(rates.Config("AddOnCount")); y++) { if (rates.Config("AddOnAmount[" + y + "]") != "") { Console.WriteLine("\t$" + rates.Config("AddOnAmount[" + y + "]") + " " + rates.Config("AddOnType[" + y + "]") + " (" + rates.Config("AddOnTypeDescription[" + y + "]") + ")"); } } Console.WriteLine("Total Cost: $" + rates.Services[x].ListNetCharge + "\r\nDelivery Date: " + rates.Services[x].DeliveryDate + "\r\n"); }

When requesting a specific service there will be multiple returned entries in the Services collection. These will be for the same service type, but with different AddOn‘s. These are extra options available for shipping a package.

Typically the more information provided about a package the more accurate the estimated rate will be. For simplicity’s sake these examples used a bare minimum of information.

Generating a Label

After getting an estimated rate for shipping a package a label will need to be generated and affixed to the packaging. Domestically shipped packages (those shipped only within the borders of the United States) will have their labels generated with the Uspsship component while all others will use the Uspsshipintl component.

To create a label Stamps.com will need to know some information about how the package should be shipped, including:

  • Who is sending the package.
  • Who is receiving the package.
  • What service will be used.
  • Basic package information like weight and packaging type.

All of this information can be set with properties and/or configuration settings. Here is an example:

Uspsship ship = new Uspsship(); ship.PostageProvider = UspsshipPostageProviders.ppStamps; ship.Config("StampsTestMode=1"); ship.LabelImageType = UspsshipLabelImageTypes.sitJPG; ship.ServiceType = ServiceTypes.stUSPSFirstClass; ship.ShipDate = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"); ship.SenderContact.FirstName = "Alice"; ship.SenderContact.LastName = "Wonderland"; ship.SenderAddress.Address1 = "101 Europa Dr."; ship.SenderAddress.Address2 = "Suite 110."; ship.SenderAddress.City = "Chapel Hill"; ship.SenderAddress.State = "NC"; ship.SenderAddress.ZipCode = "27517"; ship.RecipientContact.FirstName = "Bob"; ship.RecipientContact.LastName = "Belcher"; ship.RecipientAddress.Address1 = "Lands End Trail"; ship.RecipientAddress.City = "San Francisco"; ship.RecipientAddress.State = "CA"; ship.RecipientAddress.ZipCode = "94121"; ship.Packages.Add(new PackageDetail()); ship.Packages[0].Weight = "1.0"; ship.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging; ship.Packages[0].ShippingLabelFile = @"C:\labels\order12345.jpg"; ship.GetPackageLabel(); Console.WriteLine("Tracking Number: " + ship.Packages[0].TrackingNumber + "\r\nStampsTxId: " + ship.Config("StampsTxId"));

If the call is successful then a label will be returned and saved to the location specified with ShippingLabelFile. Alternatively the label data can be worked with by querying the ShippingLabel property.

Stamps.com will return both a tracking number, which is generated in USPS’s systems, and a StampsTxId, which is generated from Stamps.com. Either of these identifiers can be used to work with a specific package after it has been entered into their systems.

A package can be dropped off or alternatively a pickup can be scheduled. To schedule a pickup with Stamps.com use the SchedulePickup method, like in this example:

Uspsship ship = new Uspsship(); ship.PostageProvider = UspsshipPostageProviders.ppStamps; ship.Config("StampsTestMode=1"); ship.SenderContact.FirstName = "Rick"; ship.SenderContact.LastName = "Sanchez"; ship.SenderContact.Company = "n software"; ship.SenderContact.Phone = "9195447070"; ship.SenderAddress.Address1 = "101 Europa Dr"; ship.SenderAddress.Address2 = "Suite 110."; ship.SenderAddress.City = "Chapel Hill"; ship.SenderAddress.State = "NC"; ship.SenderAddress.ZipCode = "27517"; ship.CountPriority = 1; ship.TotalWeight = 1; ship.PackageLocation = UspsshipPackageLocations.plOther; ship.Config("SpecialInstructions=Packages are behind the screen door."); ship.SchedulePickup(); Console.WriteLine("The package will be picked up on " + ship.ShipDate);

When scheduling pickups the number of Priority or Express packages must be provided through the CountPriority or CountExpress properties. Additionally the TotalWeight of all packages must be provided. The address that the package(s) will be picked up from is set with SenderAddress. If the PackageLocation is plOther then SpecialInstructions also needs to be provided. Otherwise any special instructions are optional.

Tracking Packages

Once a package is in possession of USPS it can be tracked with the Uspstrack component. Tracking is fairly simple, just call the TrackShipment method and pass in a tracking number. When the response comes back from the server the method will return and any tracking events will be contained in the TrackEvents collections. Here is an example:

Uspstrack track = new Uspstrack(); track.PostageProvider = UspstrackPostageProviders.ppStamps; track.Config("StampsTestMode=1"); track.TrackShipment("1234567890"); foreach (TrackDetail trackEvent in track.TrackEvents) { Console.WriteLine("----Event----\r\n" + trackEvent.Status + trackEvent.Date + " - " + trackEvent.Time + trackEvent.City + ", " + trackEvent.State + trackEvent.ZipCode + "\r\n"); }

Shipping packages can be complicated, but we sincerely hope that 4D Shipping makes it significantly easier for you. There is more to be discovered when working with this product, like international shipping, but hopefully this is plenty to get started with. If you need any assistance while working with 4D Shipping please check out the support options below.

Getting Support

If you are stuck with 4D Shipping there are options for help. Please have a look through the Knowledge Base and Documentation first, as often many common questions can be answered there. If you are still having trouble, please contact our support team and they would be happy to help you.

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

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