4D Shipping - Getting Started with FedEx

Requirements: 4D Shipping

Introduction

4D Shipping is a toolkit that enables software developers to quickly and easily incorporate UPS, FedEx, and USPS shipping capabilities into their software applications and websites. The toolkit includes components for shipping, tracking, address verification, and rate calculation. In this tutorial we will focus on support for FedEx. The FedEx components in the toolkit are:

  • FedExAddress component: Validates recipient addresses by checking street address, city, state, and zip code, and suggests alternates if an error is discovered.
  • FedExRates component: Retrieves courtesy rate quotes from FedEx for a specific account and service types.
  • FedExShip Generates complete FedEx domestic shipping labels, including addresses and barcodes, for single and multi-package shipments (MPS).
  • FedExShipIntl component: Generates complete FedEx international shipping labels, including addresses and barcodes, for single and multi-package shipments (MPS).
  • FedExTrack component: Provides tracking information for packages.

Getting Started

Certification with FedEx

FedEx requires that all applications that print shipping labels pass a series of certification tests prior to being placed in production. The full version of FedEx Integrator gives you access to the FedEx Certify demo that makes this process very easy. The demo is included in the toolkit and includes all test scenarios required by FedEx for FedEx Express and Ground (international and domestic), and Home Delivery. Through this demo you can generate all shipping labels for selected scenarios applicable to your shipping needs with a click of a button. After you get registered for this certification you’ll also need to subscribe to FedEx Services (next paragraph).

Subscribe to FedEx Services

Before starting to use this component, all developers must first register for FedEx Web Services by visiting Developer Solution Center (DSC) at http://www.fedex.com/us/developer/ and following the instructions. At the time of registration, a Developer Key, Password, Test Account Number, and a Test Meter Number are provided to you by FedEx.

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

  1. Allow the customer to choose what type of shipping to use, and show the cost and delivery time of each choice.
  2. Print a shipping label for the package.
  3. Provide the customer with a shipment tracking number.
  4. Give the package to FedEx.

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

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

After you get the customers shipping address, you can retrieve the cost of delivery and an estimated date of delivery using the FedExRates component.

To determine the rate to ship a regular FedEx envelope from my zip code (27502) to a sample address (20770), I can use the following code:

Fedexrates Rates1 = new Fedexrates(); Rates1.FedExAccount.Server = "https://gatewaybeta.fedex.com:443/web-services/rate"; Rates1.FedExAccount.DeveloperKey = developerKey; Rates1.FedExAccount.Password = password; Rates1.FedExAccount.AccountNumber = accountNumber; Rates1.FedExAccount.MeterNumber = meterNumber; Rates1.SenderAddress.ZipCode = "27502"; Rates1.SenderAddress.State = "NC"; Rates1.SenderAddress.CountryCode = "US"; Rates1.RecipientAddress.ZipCode = "20770"; Rates1.RecipientAddress.State = "MD"; Rates1.RecipientAddress.CountryCode = "US"; Rates1.Packages.Add(new PackageDetail()); Rates1.TotalWeight = "1.0"; Rates1.RequestedService = ServiceTypes.stUnspecified; Rates1.Packages[0].PackagingType = TPackagingTypes.ptYourPackaging; Rates1.GetRates(); for (int i = 0; i < Rates1.Services.Count; i++) { string NetCharge = ""; if (Rates1.Services[i].AccountNetCharge != "") //If there is a negotiated rate NetCharge = Rates1.Services[i].AccountNetCharge; else NetCharge = Rates1.Services[i].ListNetCharge; Console.WriteLine(Rates1.Services[i].ServiceTypeDescription + " Days In Transit: " + " " + Rates1.Services[i].TransitTime + " Charge: " + NetCharge); }

Note that package weight is required for all packages, but it is only necessary to specify the dimensions of the package (length, width, and height – not shown in the example above) if you set the PackagingType to ptYourPackaging. Note that ptYourPackaging is required for FedEx Ground services.

Rates depend on location (from and destination), dimensions and/or weight, packaging type (envelope, box, etc), and service type. Available service types are:

  • Unspecified
  • Priority Overnight
  • Standard Overnight
  • First Overnight
  • FedEx 2 Day
  • FexEx Express Saver
  • FedEx Ground
  • Ground Home Delivery
  • FedEx 1 Day Freight
  • FedEx 2 Day Freight
  • FedEx 3 Day Freight
  • International Priority
  • International Economy
  • International Economy Distribution
  • International First
  • International Priority Freight
  • International Economy Freight
  • International Distribution Freight
  • Europe First International Priority
  • FedEx SmartPost
  • FedEx 2 Day AM
  • FedEx First Freight
  • FedEx International Ground
  • FedEx Freight Economy
  • FedEx Freight Priority

The ServiceType property has an “unspecified” setting that will tell the component to retrieve rates for all available service types.

fedexrates

As you can see from the above screenshot of the FedExRates demo that comes with the 4D Shipping .Net Edition, when the service type is unspecified, FedEx will return rate quotes for all applicable service types (overnight, 2 day, etc). The delivery date, charges, discounts, and other details about the rate quotes are contained in a set of Service fields like Services[i].DeliveryDate, Services[i].AccountNetCharge, etc.

2. Print a shipping label for the package.

Use the FedExShip component to generate a shipping label for your package. The component will generate labels in PDF, PNG, or thermals Elton, Zebra, and UniMark. Choose the label image type through the LabelImageType property. The FedExShip component can generate labels for all service types.

Fedexship Ship1 = new Fedexship(); Ship1.DeveloperKey = developerKey; Ship1.FedExAccount.DeveloperKey = developerKey; Ship1.FedExAccount.Password = password; Ship1.FedExAccount.AccountNumber = accountNumber; Ship1.FedExAccount.MeterNumber = meterNumber; Ship1.FedExAccount.Server = "https://gatewaybeta.fedex.com:443/xml"; Ship1.SenderContact.FirstName = "John Smith"; Ship1.SenderContact.Phone = "1234567890"; Ship1.SenderAddress.Address1 = "123 Fake St."; Ship1.SenderAddress.City = "Washington"; Ship1.SenderAddress.State = "DC"; Ship1.SenderAddress.ZipCode = "20260"; Ship1.SenderAddress.CountryCode = "US"; Ship1.RecipientContact.FirstName = "Jane Smith"; Ship1.RecipientContact.Phone = "1234567890"; Ship1.RecipientAddress.Address1 = "8 Wildwood Dr."; Ship1.RecipientAddress.City = "Durham"; Ship1.RecipientAddress.State = "NC"; Ship1.RecipientAddress.ZipCode = "27712"; Ship1.RecipientAddress.CountryCode = "US"; Ship1.ServiceType = ServiceTypes.stFedExStandardOvernight; Ship1.DropoffType = FedexshipDropoffTypes.dtRegularPickup; Ship1.LabelImageType = FedexshipLabelImageTypes.fitPNG; Ship1.Packages.Add(new PackageDetail()); Ship1.Packages[0].PackagingType = TPackagingTypes.ptLetter; Ship1.Packages[0].ShippingLabelFile = "shippinglabel.png"; Ship1.Packages[0].Weight = "1.0"; Ship1.GetShipmentLabels();

fedexshippinglabel

After the call to GetShipmentLabels, you’ll have a file called shippinglabel.png (depending on how you set the ShippingLabelFile and LabelImageType properties) that you can print, which looks something like the one pictured above. Note that if you’re using the test server, as in the example above, the label will always be the test label shown here (“TEST LABEL CONTACT”, “TEST LABEL COMPANY”, etc). Affix this label to your package and it is ready to go.

Also the DeliveryDate property will be populated with the reply from FedEx indicating when the package will be delivered.

The FedExShip component is extremely flexible and provides a wide variety of properties that can be set to effect the generated label itself. For COD shipments, you can set the CODType and CODTotalAmount properties to specify the amount and type. And set ShipmentSpecialServices to indicate that this is a COD shipment.

FedEx Express Carrier
All of the ServiceTypes except FedEx Ground and FedEx Ground Home Delivery are for FedEx Express services.

FedEx Express shipments are also eligible for FedEx Hold At Location services. Use this option if you need your package to be held at a FedEx location instead of delivered to the final destination. This is useful if you need your package earlier than the scheduled delivery time, or if you won’t be available to receive a delivery. To turn on this option, set the HoldAtLocation property to specify the location (i.e. Ship1.HoldAtLocation.Address1 = “123 My Street.”). You will also need to set ShipmentSpecialServices to indicate the HoldAtLocation is included in the request. Locations can be searched for with the FedExAddress component included in 4D Shipping.

FedEx Ground Carrier
The service types available for FedEx Ground are FedEx Ground and FedEx Ground Home Delivery.

  • End of Day Close
    If you’re shipping through the FedEx Ground carrier, you should perform the FedEx Ground End of Day Close procedure at the end of every shipping day. To perform this procedure, call the CloseGroundShipments method of the FedExShip component.

    A printed Manifest report is required to be tendered along with your packages if they are being picked up by FedEx Ground. If you are dropping the packages off at a FedEx drop-off location, the manifest is not required. After a call to the CloseGroundShipments, the manifest report will be included in its un-encoded form in the Manifest property, and also written to disk in the file specified by the CloseRequest.ReportFile property.

    The CloseGroundShipments can also be used to generate reports instead – to use the operation for this functionality, just set the CloseRequest.ReportType property to a different value. Then calling CloseGroundShipments will cause FedEx to return the specified report for the past 3 days of shipping data.

    A customer cannot cancel any shipments once they are closed out. However, shipments can be added to a day’s shipment after a close operation has been performed and multiple closes can be performed in a day.

  • FedEx Ground services also have the option of the FedEx Ground COLLECT service, explained in the Payment Options section below.

Shipping Payment Options

Payment options can be specified using the FedExShip component’s Payor property. Specifically, the payment type is set with the Payor.PayorType property, which can take 1 of 4 possible values:

  • Sender – The default, using this option means that the account identified by the AccountNumber property will be billed for the shipping charges.
  • Recipient – The recipient of the package will be billed for the shipping charges. To ship this way, you’ll need to know the recipients account number and specify it in the Payor.AccountNumber property, along with the PayorCountry.
  • Third Party – A third party will be billed for the shipping charges. To ship this way, you’ll need to know an account number and specify it in the Payor.AccountNumber property, along with the Payor.CountryCode.
  • FedEx Ground COLLECT – For FedEx Ground only, this service gives you the ability to be invoiced for incoming shipments, as opposed to paying the suppliers shipping charges. To use this service, set the Payor.PayorType property to 3 (COLLECT). Shipping charges will be billed to the account identified by the AccountNumber property.

COD – Collect On Delivery
In order to ship COD (collect on delivery) packages, use the CODType and CODTotalAmount properties. With COD, the recipient is paying for the product being shipped rather than the shipping itself. To do this, first set the ShipmentSpecialServices property to indicate a COD shipment, then set the CODType and CODTotalAmount. CODType can be CASH, GUARANTEED FUNDS (certified check, money order or cashier’s check) or ANY (any of the previous plus company or personal checks).

Signature Options

Signature options can be specified in the FedExShip component by setting the Packages[i].SignatureType property. The property has 5 possible values:

  • Service Default – The default value for the requested service.
  • Adult – A signature will be obtained from someone at the delivery address who has a government issued photo id proving that they are at least 21 years of age.
  • Direct – A signature will be obtained from someone at the delivery address.
  • Indirect – A signature will be obtained from someone at the delivery address, a neighbor, or a door tag.
  • No Signature – Only available for FedEx Express shipments that are not alcohol, hold at location, dangerous goods, and have a declared value less than $500.

International Shipments
For international shipments, FedEx Express requires a Commercial Invoice document (which you must print yourself). The FedExShipIntl component has a Commodities collection where you can add a new Commodity and specify the Description, Weight, etc. You’ll need to use these properties to build your ship request if you are shipping internationally, and FedEx will automatically forward this commodity information to customs. Speaking of customs, you’ll also need to set the TotalCustomsValue property to the total value of the shipment, including freight, insurance, and other charges.

Also required for dutiable shipment is the DutiesPayor property. This property should be set to indicate who will be paying the duty for the shipment – the sender, the recipient, or a third party.

3. Provide the customer with a shipment tracking number.

The FedExShip component that you use in step 3 will provide you with a tracking number automatically. The component has a MasterTrackingNumber property where this information is provided after the call to GetShipmentLabels returns if the shipment was a MPS shipment. Individual package tracking numbers can be obtained by checking the Packages[i].TrackingNumber property

With this tracking number you can use the FedExTrack component of the FedEx Integrator 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 FedEx website and do their shipment tracking there. But the FedExTrack component would be particularly useful to the merchant for automatically confirming delivery of all packages sent. Here is an example:

Fedextrack Track1 = new Fedextrack(); Track1.FedExAccount.DeveloperKey = developerKey; Track1.FedExAccount.MeterNumber = meterNumber; Track1.FedExAccount.Password = password; Track1.FedExAccount.AccountNumber = accountNumber; Track1.FedExAccount.Server = "https://gatewaybeta.fedex.com:443/xml"; Track1.TrackShipment("<insert tracking number>"); for (int j = 0; j < Track1.PackageCount; j++) //For each package in the shipment { Track1.PackageIndex = j; //Here you can check properties like PackageServiceTypeDescription, etc. Console.WriteLine("Ship via : " + Track1.PackageServiceTypeDescription); Console.WriteLine("Tracking number : " + Track1.PackageTrackingNumber); Console.WriteLine("Other identifier : " + Track1.PackageReferences); Console.WriteLine("Delivery Date : " + Track1.PackageDeliveryDate); Console.WriteLine("Delivered Status : " + Track1.PackageDeliveryStatus); Console.WriteLine("Delivery Location : " + Track1.PackageDeliveryLocation); Console.WriteLine("Signed by : " + Track1.PackageSignedBy); for (int i = 0; i < Track1.TrackEvents.Count; i++) //For each scan for the package { //Here you can check details about individual package scan activity Console.WriteLine(Track1.TrackEvents[i].Date); Console.WriteLine(Track1.TrackEvents[i].Time); Console.WriteLine(Track1.TrackEvents[i].Status); } }

fedextrack

4. Give the Package to FedEx.

Now that the order process is complete, its time (hopefully) to actually ship the product to the customer. The procedure for getting your package into the hands of FedEx depends on the value of the DropoffType property when you created the shipping label with the FedExShip component. Possible options are:

  • Regular Pickup – The shipper already has an every-day pickup scheduled with a courier.
  • Request Courier – The shipper will call FedEx to ask for a courier.
  • Drop Box – The shipper will drop the package in a FedEx drop box.
  • Business Service Center – The shipper will drop off the package at an authorized FedEx business service center.
  • Station – The shipper will drop off the package at a FedEx Station.

You can use the FedExAddress component to search for FedEx Stations and FedEx authorized service centers in close proximity to your location. All done, happy shipping!

Conclusion

This article demonstrates the ease of use of the 4D Shipping. In this tutorial we went over some of the most commonly used components and uses, however if there are any questions not covered here please do not hesitate to contact us via the link at the bottom of this page.

Notes:

  • DeveloperKey, Password, AccountNumber and MeterNumber properties are required for all FedEx transactions.
  • The test server URL for all requests is “https://gatewaybeta.fedex.com:443/xml”.
  • The live production URL will be provided to you by FedEx after your application has been approved/certified by FedEx Web Integration Solutions team.

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