FedEx Shipping API and Developer Tools

FedEx offers a robust suite of RESTful APIs designed to seamlessly integrate shipping functionalities into applications. Whether you need to generate shipping labels, retrieve rate quotes, track packages, or validate addresses, the FedEx API platform covers every aspect of the shipping lifecycle. This guide provides developers with insights into the API architecture, authentication processes, key endpoints, and best practices for effective production integrations.

API Platform Overview

In the transition from legacy SOAP-based Web Services to a modern RESTful API platform during 2022-2023, FedEx embraced a more efficient approach. The new platform uses OAuth 2.0 for authentication, facilitates JSON request/response bodies, and adheres to standard REST conventions, making it more accessible and intuitive for developers.

Available APIs

FedEx's RESTful API suite includes various specialized tools:

Ship API: This API is central to creating shipments and generating labels. It facilitates the generation of shipping labels and manifests, making it a crucial tool for businesses that handle numerous shipments daily.
Rate API: This API provides rate quotes and transit times, aiding businesses in rate shopping and cost estimation. By understanding the costs upfront, businesses can better plan and budget for shipping expenses.
Track API: Enables tracking of packages through tracking numbers, providing real-time status updates. This is essential for businesses and customers to stay informed about the whereabouts of shipments.
Address Validation API: Validates and corrects addresses, ensuring accuracy in checkout forms and address books. This reduces the risk of delivery failures and additional fees due to incorrect addresses.
Pickup API: Facilitates the scheduling and cancellation of pickups, streamlining the process of automated pickup requests for businesses.
Service Availability API: Checks available services for a particular route, enabling businesses to select the most suitable service for their needs.
Ground End of Day API: Assists in closing out Ground shipments, which is essential for daily ground batch processing.
Document API: Manages customs documents, an essential feature for businesses engaged in international shipping.
Location API: Helps find FedEx locations, useful for customers looking for store locators or drop-off points.
Freight LTL API: Integrates LTL freight shipments into the business operations, catering to those needing freight shipping solutions.

API Environments

The FedEx API offers two main environments:

Sandbox: Use this for development and testing. It simulates realistic responses without generating actual shipments or incurring charges, allowing for safe experimentation and troubleshooting.
Production: This is the live environment where real shipments are processed. Ensure thorough testing in the sandbox environment before transitioning to production to avoid errors and issues.

Getting Started

Step 1: Create a FedEx Developer Account

To begin using the FedEx APIs, create a developer account:

Visit developer.fedex.com.

Click "Sign Up" to create your account.

Verify your email address.

Accept the API License Agreement to proceed.

Step 2: Create an API Project

Once you have an account:

Navigate to "My Projects" and click "Create a Project".

Select the APIs you wish to utilize.

Choose whether your project will be in the sandbox or production environment.

FedEx will generate the necessary credentials for your project.

Step 3: Obtain API Credentials

After setting up your project, you'll receive various credentials:

API Key: This is a public identifier for your application, used in every API request header.
Secret Key: Used only for OAuth token requests, this key must remain private.
Account Number: Required for shipment and rate requests, linking your API usage to your FedEx account.
Meter Number: A legacy identifier that might still be needed for some API calls.

Security Tip: Always store your Secret Key securely. It should never be exposed in client-side code, version control systems, or public repositories. Use environment variables or a secrets manager for safe storage.

Authentication (OAuth 2.0)

FedEx uses the OAuth 2.0 Client Credentials flow for API authentication, ensuring secure access to its services.

Getting an Access Token

To obtain an access token, send a POST request to the authentication endpoint:

Endpoint: POST /oauth/token
Request body (form-encoded):
grant_type: client_credentials
client_id: your API Key
client_secret: your Secret Key

The response will include an access_token and its expiration time, generally valid for 3,600 seconds (1 hour).

Token Management Best Practices

Efficient token management is crucial for maintaining smooth operations:

Cache tokens: Store and reuse tokens until they are close to expiration.
Refresh proactively: Request a new token five minutes before the current one expires.
Handle 401 errors: Refresh the token and retry if a request returns a 401 error.
Ensure thread safety: Use thread-safe methods for token storage in multi-threaded applications.
Mind rate limits: The token endpoint has its own rate limit, so avoid requesting new tokens for every API call.

Rate API

The Rate API provides detailed shipping rates, including transit times and surcharges, based on specified shipping parameters.

Key Request Parameters

When requesting rates, ensure you include the following parameters:

shipper.address: The origin address, including city, state, ZIP, and country.
recipient.address: The destination address.
requestedPackageLineItems: Details of the package, including dimensions and weight.
pickupType: Options include DROPOFF_AT_FEDEX_LOCATION or USE_SCHEDULED_PICKUP.
serviceType: Specify a service or leave it blank to get all available options.
packagingType: Options include YOUR_PACKAGING, FEDEX_ENVELOPE, FEDEX_PAK, etc.
preferredCurrency: Specify the currency for the rate (e.g., USD, CAD, EUR).

Rate Response Structure

The API response will provide:

Base rate for each available service.
Detailed breakdown of surcharges.
Fuel surcharge amount.
Total charges.
Estimated delivery date and transit time.
Service-specific delivery commitments.

Rate Shopping Tips

Request all services: By omitting serviceType, you can compare rates across all available services in a single request.
Accurate dimensions: Provide precise package dimensions to ensure correct DIM weight pricing.
Residential indicator: Specify if the destination is residential to factor in any surcharges.
Rate Type Awareness: Understand whether you are viewing LIST, ACCOUNT, or INCENTIVE rates.
Cache rate responses: To minimize API calls, cache rate responses for 15-30 minutes if multiple requests for identical quotes are anticipated.

Ship API

The Ship API is crucial for creating shipments and generating shipping labels in various formats.

Creating a Shipment

When creating a shipment, the following parameters are essential:

shipper: Include name, address, phone number, and FedEx account number.
recipients: Provide name, address, and phone number of the recipient.
pickupType: Specify the method of pickup.
serviceType: Choose from options like FEDEX_GROUND, PRIORITY_OVERNIGHT, etc.
packagingType: Specify the type of packaging.
requestedPackageLineItems: Provide details such as weight, dimensions, and package count.
labelSpecification: Define the label format and size.
shippingChargesPayment: Indicate who will pay for the shipping charges (sender, recipient, or a third party).

Label Formats and Sizes

Labels can be generated in several formats and sizes to accommodate different printing needs:

Formats: PDF for standard printers, PNG for thermal printers, and specialized formats like ZPL, EPL, and DPL for specific thermal printers.
Sizes: Choose based on your printer and label requirements, such as 4" x 6" for standard labels or 8.5" x 11" for full-page labels.

Multi-Piece Shipment (MPS)

For shipments involving multiple packages to the same recipient:

Create a master shipment with the first package.

The response will include a masterTrackingId.

Add subsequent packages, referencing the masterTrackingId.

Each package will receive its own tracking number and label.

The entire group will be processed together through the FedEx network.

Void/Cancel a Shipment

To void a shipment, issue a PUT request with the tracking number. This action can only be performed before the package is picked up by FedEx. If the package is already in transit, you'll need to contact FedEx customer service for assistance.

Track API

The Track API delivers real-time tracking information, enabling businesses to monitor package status, location, and estimated delivery times.

Tracking by Number

To track a package, use:

trackingNumberInfo.trackingNumber: The FedEx tracking number.
includeDetailedScans: A Boolean value indicating whether to include all scan events.

Tracking Response Data

The response provides comprehensive details:

latestStatusDetail: Current status, such as In Transit or Delivered.
dateAndTimes: Key dates like shipment, estimated delivery, and actual delivery.
scanEvents: An array of tracking events with timestamps and locations.
deliveryDetails: Information such as who signed for the delivery and where it was delivered.
shipperInformation: Details about the origin of the shipment.
recipientInformation: Details about the destination.

Tracking Event Types

Common event types include:

PU: Picked up
IT: In transit
OD: On FedEx vehicle for delivery
DL: Delivered
DE: Delivery exception
SE: Shipment exception
CA: Shipment cancelled
HL: Held at location
RS: Return to shipper

Webhook Notifications

Instead of continuously polling the Track API, you can register for webhooks to receive push notifications when tracking events occur. This is a more efficient method for applications requiring real-time tracking updates.

Registration: Done via the FedEx Developer Portal or API.
Events: Configurable per event type.
Delivery Method: HTTPS POST to your endpoint with a retry policy for failed attempts.
Payload Format: JSON matching the Track API response format.
Authentication: Ensures security through webhook signature verification.

Address Validation API

The Address Validation API ensures that addresses are correct before shipping, reducing delivery failures and associated fees.

Validation Response Data

The API response provides:

resolvedAddresses: An array of corrected address suggestions.
classification: Indicates whether the address is RESIDENTIAL, BUSINESS, or MIXED.
attributes: Lists any address attributes, such as PO Box or suite numbers.
customerMessages: Warnings or issues identified with the address.

Address Classification

The classification helps determine the appropriate shipping service:

RESIDENTIAL: Suitable for homes, apartments, and condos, typically requiring FedEx Home Delivery.
BUSINESS: For commercial addresses like offices and warehouses, best served by FedEx Ground.
MIXED: Requires verification, as it could be either.
UNKNOWN: Defaults to residential classification.

Validation Best Practices

Validate at checkout: Catch and correct errors before order completion.
Show suggestions: Present corrected addresses for customer confirmation.
Store classification: Cache the residential/business flag to assist in service selection.
Handle partial matches: Provide multiple suggestions if validation is ambiguous.
International addresses: Follow country-specific formatting rules to ensure accuracy.

Error Handling

FedEx API errors are structured with error codes and descriptive messages, helping diagnose and resolve issues efficiently.

Common Error Codes

FORBIDDEN.ERROR: Indicates an authentication issue; refresh the OAuth token.
SERVICE.UNAVAILABLE: The FedEx system is down; retry using exponential backoff.
VALIDATION.ERROR: Indicates invalid request data; check and correct the request body.
SYSTEM.ERROR: Internal FedEx error; retry and contact support if the issue persists.
NOT.FOUND.ERROR: Resource not found; verify tracking numbers or shipment IDs.
RATE.LIMIT.EXCEEDED: Too many requests; implement rate limiting and caching.

Retry Strategy

Implement a strategic retry mechanism for handling errors:

401 Unauthorized: Retry immediately after refreshing the token.
429 Rate Limited: Use exponential backoff (e.g., 2s, 4s, 8s, 16s).
500 Server Error: Retry with exponential backoff (1s, 2s, 4s).
503 Service Unavailable: Implement a similar backoff strategy (5s, 10s, 20s).
400 Bad Request: Correct the request before retrying.
404 Not Found: Verify and correct input data.

Rate Limits

FedEx enforces rate limits per API key and account to maintain system stability and performance.

Default Rate Limits

Each API has specific limits:

Rate API: 10 requests per second, with a daily limit of 10,000.
Ship API: Same as Rate API.
Track API: Follows similar limits.
Address Validation: Also capped at 10 requests per second.
OAuth Token: Limited to 5 requests per second and 1,000 per day.

Increasing Limits

For high-volume integrations, request a rate limit increase through the FedEx Developer Portal. Provide your use case, expected volume, and current limits. Approval generally takes 1-2 weeks.

Testing and Certification

Sandbox Testing

The sandbox environment is ideal for testing without the risk of creating real shipments. Key differences include:

Shipments: Simulated rather than real.
Charges: No real billing occurs.
Labels: Marked as "SAMPLE" for testing clarity.
Tracking: Simulated events rather than real-time updates.
Addresses: Any format is accepted, but real addresses are required in production.

Certification Process

Before using the Ship API in production, certification is required:

Submit test shipments: Use the sandbox API to create test shipments.

Label validation: FedEx will review generated labels for compliance.

Scenario testing: Complete specified shipping scenarios, including domestic, international, and multi-piece shipments.

Review period: FedEx reviews the integration (1-3 weeks).

Approval: Production credentials are released upon approval.

The Track and Rate APIs typically don't require certification for production use.

Integration Architecture Best Practices

1. Use an Abstraction Layer

Create a carrier-agnostic shipping interface that encapsulates FedEx-specific API calls. This approach simplifies adding additional carriers like UPS or USPS without altering core application logic. Platforms like atoship offer this abstraction, providing a unified interface for multiple carriers.

2. Implement Idempotency

Ensure that shipping label creation is idempotent. If a network error occurs after FedEx creates the label but before you receive the response, a retry should not result in duplicate labels. Use unique transaction IDs to prevent duplication.

3. Store Complete Responses

Maintain a record of the full FedEx API response for each transaction. This information is invaluable for debugging, reconciling invoices, generating shipping reports, and filing claims with comprehensive documentation.

4. Monitor API Health

Track essential metrics to ensure the health of your FedEx integration:

API response time: Target under 2 seconds; alert if over 5 seconds.
Error rate: Keep below 1%; alert if over 3%.
Token refresh success: Should always be 100%; alert on any failure.
Label generation success: Aim for over 99%; alert if below 97%.
Rate response completeness: Ensure 100% coverage; alert if services are missing.

5. Handle Graceful Degradation

If the FedEx API becomes unavailable, your application should:

Display cached rates from the last successful query.
Queue label generation requests for later processing.
Notify the operations team about the outage.
Switch to alternative carriers if possible.
Avoid displaying errors to end-users; instead, provide friendly messages.

The FedEx RESTful API platform offers extensive capabilities for developers to build comprehensive shipping integrations. Start with the Rate and Track APIs for rapid implementation, then expand to the Ship API for label generation. Thoroughly test in the sandbox environment before moving to production, and prioritize robust error handling, rate limiting, and monitoring. For businesses looking to streamline the process, platforms like atoship offer pre-built FedEx integrations, simplifying the setup while maintaining full API functionality.