Shipping APIs - FedEx

In my last post I talked about an API for shipping via USPS, and promised a similar walk-through for shipping via FedEx.  Well, here it is - an introduction to adding FedEx shipping to your desktop and web applications using the IBiz FedEx Integrator.

IBiz FedEx Integrator is a tookit that enables software developers to quickly and easily incorporate FedEx shipping capabilities into their software applications and websites.  The toolkit includes components for shipping, tracking, and rate calculation:

  • Locator component: Used to locate FedEx locations that are close to a given address or telephone number.
  • Rates component: Retreives courtesy rate quotes from FedEx for a specific account and service types.
  • Ship component: Generates FedEx shipping labels complete with address and barcodes. This component also gives you the ability to cancel a shipment or close out FedEx Ground shipments.
  • Track component: Provides tracking information for packages.
  • Subscribe component: Provides a unique meter number specific to the customer's FedEx account.


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 IBiz FedEx Integrator gives you access to a certification package that makes this process very easy. The certification package is available by request to all owners of any licensed version of IBiz FedEx Integrator.  It includes all test scenarios required by FedEx for FedEx Express and Ground (international and domestic), and Home Delivery. Through the application included in the certification package 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).

To request materials for certification please contact /n software support.

Subscribe to FedEx Services

Before you can communicate with FedEx electronically you need to have both a FedEx account number and a FedEx meter number.  First you must have a FedEx account number, then you can use the Subscribe component included in the IBiz FedEx Integrator to subscribe to FedEx Services and get a meter number assigned to your account number.  This subscription is a one-time process.

The response to the Subscribe component's Register method will contain your assigned FedEx Meter Number as well as which FedEx services are authorized for that particular FedEx Account.

You will need to submit this subscription request twice:

  • Once after you are registered in the FedEx Test Environment. To register in the FedEx Ship Manager (FSM) Direct program, go to http://www.fedex.com/us/solutions/wis/.
  • Once after you are certified to access the FedEx Production Environment.

You should record the returned meter number and use it with each request sent to 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 Rates 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:

  Rates1.ServerURL = https://gateway.fedex.com:443/GatewayDC;
Rates1.AccountNumber = acctnum;
Rates1.MeterNumber = meternum;
Rates1.FromPostalCode = "27502";
Rates1.FromState = "NC";
Rates1.DestinationPostalCode = "20770";
Rates1.DestinationState = "MD";
Rates1.PackagingType = ptFedexEnvelope; //0
Rates1.Weight = "1";
Rates1.Value = "10.00"; //0
Rates1.ServiceType = stUnspecified; //0, show all service type rates
Rates1.GetRates();

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), carrier code, and service type.   Available service types are:

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

The ServiceType property has an "unspecified" setting that will tell the component to retrieve rates for all available service types.  The CarrierCode property allows you to specify the carrier that will be used, either FDXE (FedEx Express, the default) or FDXG (FedEx Ground).

Rates for shipping a 1 lb package from NC zip code 27714 to NY zip code 10001 

As you can see from the above screenshot of the Rates demo that comes with the FedEx Integrator .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 properties like ServiceDeliveryDate, ServiceDiscNetCharge, etc.

2.  Print a shipping label for the package.

Use the Ship components 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 Ship component can generate labels for all service types.

  Ship1.AccountNumber = acctnum;  
Ship1.MeterNumber = meternum;
Ship1.ServerURL = "https://gatewaybeta.fedex.com:443/GatewayDC";
Ship1.FromName = "John Smith";
Ship1.FromAddress1 = "475 L'Enfant Plaza, SW";
Ship1.FromCity = "Washington";
Ship1.FromState = "DC";
Ship1.FromPostalCode = "20260";
Ship1.FromCountry = "US";

Ship1.FromPhoneNumber = "1234567890";
Ship1.ToName = "Jane Smith";
Ship1.ToAddress1 = "8 Wildwood Drive";
Ship1.ToCity = "Durham";
Ship1.ToState = "NC";
Ship1.ToPostalCode = "27712";
Ship1.ToCountry = "US";
Ship1.ToPhoneNumber = "1234567890";
Ship1.Weight = 1; //lbs
Ship1.CarrierCode = "FDXE"; //FedEx Express
Ship1.ServiceType = stStandardOvernight; //1, standard overnight
Ship1.DropoffType = dtRegularPickup; //0, regular pickup
Ship1.DropoffType = dtRegularPickup; //0, regular pickup
Ship1.LabelImageType = ltPNG; //1, PNG file
Ship1.ShippingLabelFile = "shippinglabel.png";
Ship1.ShipPackage();

FedEx Shipping Label
After the call to ShipPackage, 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 along with postage and it is ready to go. 

Also the DeliveryDate and DeliveryDay (day of week) properties will be populated with the reply from FedEx indicating when the package will be delivered.

The Ship 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 COD property to true and set the CODAmount and CODType with the details of the payment itself.

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 true, and specify the location in the other HoldAt properties (HoldAtAddress, HoldAtCity, etc).  Locations can be searched for with the Locator component included in IBiz FedEx Integrator.

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 (i.e., the CarrierCode property is set to "FDXG"), you should perform the FedEx Ground End of Day Close procedure at the end of every shipping day.  To perform this procedure, call the CloseOperation method.
    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 CloseOperation, the manifest report will be included in its unencoded form in the Manifest property, and also written to disk in the file specified by the ReportFile property. 
    The CloseOperation can also be used to generate reports instead - to use the operation for this functionality, just set the ReportOnly property to true and set the ReportIndicator property to the type of reports you'd like to generate.  Then calling CloseOperation will cause FedEx to return the specified report (in either the Manifest, MultiweightReport, HazMatCertificate, or CODReport properties, depending on the value of ReportIndicator) 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 Ship component's Payor properties.  Specifically, the payment type is set with the 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 PayorAccountNumber 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 PayorAccountNumber property, along with the PayorCountry.
  • 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 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 COD properties.  With COD, the recipient is paying for the product being shipped rather than the shipping itself.  To do this, first set the COD property to true, then set the CODType and CODAmount.  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 Ship component by setting the SignatureOption property.  The property has 4 possible values:

  • 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.
  • Indirect - A signature will be obtained from someone at the delivery address, a neighbor, or a door tag. 
  • Direct - A signature will be obtained from someone at the delivery address.
  • 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.

International Shipments

International shipments can either contain only documents, or can contain no documents at all.  For international shipments that are not documents, FedEx Express requires a Commercial Invoice document, commonly called a "CI", which you must print yourself.  The Ship component has a set of Commodity properties such as CommodityCount, CommodityDescription, CommodityWeight, 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.

By default the IBiz FedEx Ship component assumes you are not shipping documents.  If you are shipping documents, you'll need to tell the component this by setting the Documents config setting to true (Ship1.Config("Documents=true")).

Also required for dutiable shipment is the DutiesPayorType 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 Ship component that you use in step 3 will provide you with a tracking number automatically.  The component has a TrackingNumber property where this information is provided after the call to ShipPackage returns.

With this tracking number you can use the Track component of IBiz 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 Track component would be particularly useful to the merchant for automatically confirming delivery of all packages sent.  Here is an example:

  //test server
Track1.ServerURL = "http://testing.shippingapis.com/ShippingAPITest.dll";
Track1.DetailScans = true;
Track1.TrackByTrackingNumber("<insert tracking number>");

Track a FedEx Shipment

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 Ship 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.TBD
  • 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 Locator component to search for FedEx Stations and FedEx authorized service centers in close proximity to your location.  All done, happy shipping!

Conclusions

This article demonstrates the ease of use of the IBiz FedEx 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 me via the link at the top or bottom of this page.

Notes:

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

Print | posted on Wednesday, July 18, 2007 1:49 PM

Feedback

# re: Shipping APIs - FedEx

Left by Kevin at 8/16/2007 10:29 AM
Gravatar Thanks for the artice! Very informative.

# re: Shipping APIs - FedEx

Left by Ryan at 9/12/2007 8:14 PM
Gravatar Just to let you know, to send documents or letters internationally you do not need a ci.

# re: Shipping APIs - FedEx

Left by Lance at 9/13/2007 9:47 AM
Gravatar Ryan, this is correct. I will update the article to make a note of this.

# re: Shipping APIs - FedEx

Left by Daniel at 5/22/2008 7:44 PM
Gravatar so how are package dimensions set if you do use your own packaging?

# re: Shipping APIs - FedEx

Left by Lance at 5/23/2008 10:49 AM
Gravatar Daniel - in the example above I used the default PackagingType (FedEx Envelope), but the Ship component also allows you to set the PackagingType property to Pak, Box, Tube, 10kb box, 25kb box, and "Your Packaging". For "Your Packaging", the component has a set of package dimension properties (PackageHeight, PackageWidth, etc) that are used for this.

# re: Shipping APIs - FedEx

Left by Daniel at 6/23/2008 7:22 PM
Gravatar i was able to set the dimensions, however it still doesn't seem to be using them in the calculation...i must be missing something still.

# re: Shipping APIs - FedEx

Left by Kimberly at 7/24/2008 4:13 AM
Gravatar Has anybody set Fedex Module for shipping estimation after Fedex.com had included Fuel Surcharge into shipping estimation?

# re: Shipping APIs - FedEx

Left by Spencer at 7/24/2008 9:50 AM
Gravatar When using the Rates component you can obtain the Fuel surcharge (or any other surcharge) by using the ListSurchargeAggregate configuration setting.

If you're getting a rate for a specific ServiceType, you can output the entire surcharge aggregate by doing:

Console.WriteLine(rates.Config("ListSurchargeAggregate"));

You can get specific values from within the surcharge aggregate directly from the component by using the XPath configuration setting. For fuel this would be:

Console.WriteLine(rates.Config("Xpath=/FDXRateReply/EstimatedCharges/ListCharges/Surcharges/Fuel"));

# re: Shipping APIs - FedEx

Left by abhishek at 12/25/2008 5:23 AM
Gravatar How can i integrate the FedeX shipping services into my web application(vb.net)

# re: Shipping APIs - FedEx

Left by Lance at 12/29/2008 9:22 AM
Gravatar You put it in a web app the same way you would in a windows app... ?

# re: Shipping APIs - FedEx

Left by abhishek at 12/29/2008 11:24 AM
Gravatar I am integrating Fedex into WEb application to estimate the shipping cost of the product.My application is in VB.net 2003 and fedEx web services is in vb.net2005.Can u tell step by step how can i do integration into it.
Thanks!

# re: Shipping APIs - FedEx

Left by Gaurav Agarwal at 4/18/2009 12:35 AM
Gravatar Can you please show how you created the Ship component using the vb as example and what dlls has to be installed before running the ship component?

# re: Shipping APIs - FedEx

Left by mike starks at 11/30/2009 2:54 AM
Gravatar I want to use fedex api with our cart. So when a customer checks out, a tracking number / fedex label is supplied instataneously. we only ship 1 product, 1 weight, 1 method- ground

is this possible?

# re: Shipping APIs - FedEx

Left by Fedex Commercials at 1/15/2010 12:18 PM
Gravatar Wow, that Fedex Integrator software is extremely expensive. I'm trying to make the api work by php with a clients site, however when the PDF is produces, the stupid thing has printer margins, and it doesn't produce the label properly. And that certification that fedex requires is a lot of hassle.

# re: Shipping APIs - FedEx

Left by Piyush at 4/13/2011 12:31 AM
Gravatar Have you used tracking by tracking number Webservice of fedex..?

# re: Shipping APIs - FedEx

Left by Darrel Wright at 6/3/2011 8:33 PM
Gravatar Good article, but .... how do I connect their stuff into my vb.net 2010 application. I am missing something (probably in my mind!).

Thanks!

# re: Shipping APIs - FedEx

Left by Mayank vishnoi at 8/4/2011 3:58 AM
Gravatar Its a really very nice article.for the easy understand the things.(Thankx)

# re: Shipping APIs - FedEx

Left by yogendra gupta at 11/9/2011 6:32 AM
Gravatar I am calculating shipping cost using fedex web service, I am getting difference in shipping cost calculating from site and calculating by your code. Can anyone suggest me something..

thanks in advance

# re: Shipping APIs - FedEx

Left by divya at 11/11/2011 5:04 AM
Gravatar Hi,
I have small problem with fedex service type in my application.How can i send fedex service type dynamically to the fed ex api.My application is working for only one servicetype i.e predefined in Fedex Api.I am using test account for testing.

# re: Shipping APIs - FedEx

Left by Erp at 1/10/2012 12:34 AM
Gravatar Hi,

What about the FedEx Address Component, please add this on this article.

Thanks,
Erp

# re: Shipping APIs - FedEx

Left by Irulappan at 4/28/2012 1:20 AM
Gravatar if any one have FedEx API for rates...

Your comment:





 
 

Copyright © Lance Robinson

Design by Bartosz Brzezinski

Design by Phil Haack Based On A Design By Bartosz Brzezinski