FedEx APIs Integration Best Practices

This is a quick reference guide intended to help API consumers understand ways to improve integration experience with FedEx and ensure the quality of integration solution in terms of design, speed and security.

To efficiently integrate with FedEx APIs, developers should follow these integration best practices:

API URIs

• There are separate API URIs for test and production. 
• Developers should use the test URIs for development and integration testing and the production URI for production.

Listed are the API URIs:

Test: https://apis-sandbox.fedex.com/

Production: https://apis.fedex.com/

Credential management

• API Key and Secret Key

• Your API Key and Secret Key are used to identify your application and need to be used in OAuth token request.

1. Your API Key and Secret Key should be treated very securely. Do not distribute API Key or Secret Key via email or distributed code including client-side JavaScript.
2. Your application will be compromised if your API Key or Secret Key are stolen. If you suspect that your credentials are stolen or compromised, please recreate the Secret Key immediately.
3. Avoid logging sensitive information such as Secret Key.

• Do not hardcode the API Key and Secret Key in your code.
• Your application should be dynamically able to update the API Key and Secret Key.
• The client credentials should be stored in a vault/a safe place so that it cannot be compromised.

• OAuth token

• The access token should be stored on the web application server only and must not be exposed to the browser.
• Do not hardcode the token in your applications.
• Secure the access tokens to avoid compromising them.
• Avoid making multiple calls to the OAuth token API for a new access token. It is recommended to cache the access token until the HTTP error code 401 is observed. Regenerate the OAuth token at that time.
• Do not expose the token to the end user or application.
• Use HTTPS for any API transaction.

Coding practices

• To maintain compliance with the latest and most secure data encryption communication protocol, it is recommended to use Transport Layer Security (TLS) version 1.2 or higher.
• Do not forget to set the right API headers needed for each API request. You will find the header information under each API documentation page. 
• The ’Content-Type’ in HTTP POST should be ‘application/json’.
• Please refer to the sample code to get started with each API. Each API endpoint is accompanied by several samples that will help you understand required elements, formats and other details.
• When users or developers send many decimals in their values, it can cause odd errors. For weight and currency value/amount, only two explicit decimal places are allowed. Dimensions – such as length, width and height – do not support decimals.

Example: Weight: 45.26, currency value/amount: 100.52, length: 10, width: 25, height:15.

• Avoid sending empty elements.

Example: “Streetlines”:””

• Only send data necessary to process the request.

For example, for a U.S. domestic shipment, avoid sending the commercial invoice and commodity data that may only be required for international shipments.

• When developing, determine how to react if a non-required reply element, such as a rate, is not returned. Evaluate the transaction reply for missing elements before using data.

For example, it is possible to ship a package if the rating is not functional. Test the transaction reply for missing elements before using data.

• In general, avoid hard dependencies on FedEx API integration when applicable.
• In order to reduce latency and get accurate results, the following should be used:
  
  • Filtering - Use this to narrow down the search with the parameters you are looking for.
  • Sorting - Use this to sort the results by a certain parameter in ascending or descending order.
• Validate that required fields – such as recipient postal code and package weight – have data before sending the transaction. Validate the data is appropriate for the field in question. This will minimize transaction errors.
  

For example, for US postal codes, verify that the field is all numeric and is in the form of a 5-digit or a ZIP+4 postal code format.

• To avoid adverse impact on the FedEx system availability and reliability:
  
  • Do not run performance testing in the test or production environment.
  • Have coding logic in place to keep the same transaction from failing repeatedly.
• The throttling limit is set to 750 transaction over 10 seconds. If this limit is reached in the first few seconds, HTTP error code 429 Too many requests will be returned and transactions will be restricted until 10 seconds is reached; transactions will then resume again.
  

For example, if we receive 750 requests in the first four seconds, an HTTP error code 429 Too many requests - ‘We have received too many requests in a short duration. Please wait a while to try again.’ will be returned and transactions will be restricted for the next six seconds and then resume again.

• Do not hardcode business rules like service types, package types, weight limits, etc. for shipments since they are subject to change.

Error handling

Each API response will contain an HTTP status code and response payload. Some responses will be accompanied with an error, warning or note, as applicable. Warnings and notes are not indications of a failure; however, the error or warning message should be logged and examined. Proper error handling will ensure that your integration with FedEx goes smoothly and could help avoid breakage.

HTTP status codes

Rate

• There are two ways to get a rate quote:
  
  • Rate for a specific serviceType - The results will be filtered by the serviceType value indicated. This will decrease the size of the reply and reduce the transaction response time.
    

    Example: STANDARD_OVERNIGHT

  • Rate shop – If no serviceType is indicated, then all the applicable services and corresponding rates will be returned.
• Use the Service Availability API to determine which services, package options and special services are available for a given origin-destination pair, and pass the serviceType and package option in the Rate request.
  

  For example, STANDARD_OVERNIGHT (among others) is not available between all postal codes.

• For a special service to be applied on a shipment, the special service type and its details must be included. 
  
  • Note: Some special services do not have details.
• View the Rate API documentation.

Ship

• Use the Service Availability API to determine which services are available for a given origin-destination pair and pass the serviceType and package option in the Ship request.
• For a special service to be applied on a shipment, the special service type and its details must be included.
  
  • Note: Some special services do not have details.
• Perform the close for FedEx Ground at the end of the shipping day before the shipment is picked up.
  
• View the Ship API documentation.
  

Track

• Limit the number of tracking numbers in a single-track request to 30. This will decrease the size of the reply and reduce the transaction response time.
• Limit the number of times a package is tracked to what is necessary for business needs.
• For batch tracking, remove any packages that have returned a track status of “delivered” from batch.
• View the Track API documentation.

Address Validation

• FedEx provides Address Validation as a suggestion and not a final determination. The end user needs to make a final determination of whether an address is usable from the data provided and their business needs. A process must be in place to handle addresses that cannot be validated so orders can still be processed.
• To ensure a better shipping experience, do not make the shipping process dependent on optional services such as Address Validation.

For example, if Address Validation API is unavailable at the time of order entry or shipping, a contingency should be in place to complete the shipment.

• View the Address Validation API documentation.
  

FedEx Locations Search

• Narrow your search by providing specific attributes (i.e., type of location, services offered, etc.) to get suitable location options and faster response time.
• View the FedEx Locations Search API documentation.
  

Pickup Request

• Do not input past ready time, past date or a date that is too far in the future for scheduling a pickup.
• Anonymous pickups are not allowed.
  
• View the Pickup Request API documentation.
  

Service Availability

• To get results for multiple operating companies like FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) and FedEx Ground® Economy, either omit the carrierCodes element or send separate service availability requests since multiple carrier codes cannot be specified.
• Please ensure that you have preapproval for individual skids of 151 lbs. or more and skids exceeding 2,200 lbs.
  
• If you specify SATURDAY_DELIVERY for variable options, you will get both Saturday delivery options and regular options for all services where Saturday delivery is an option. Do not specify SATURDAY_DELIVERY for special services, or it will only return any applicable Saturday delivery options.
• View the Service Availability API documentation.

Customer support

If you have questions or need assistance, we’re here to help! Please go to our Support page for resources and information on ways to contact us.