README

A comprehensive Laravel package for integrating with the FedEx REST API. This package provides OAuth 2.0 authentication, automatic token management, shipment creation, tracking, and more. Built with modern PHP practices and Laravel conventions.

Installation

You can install the package via composer:

composer require smart-dato/fedex-sdk

Publish the configuration file:

php artisan vendor:publish --tag="fedex-config"

Environment Variables

Add the following variables to your .env file:

# FedEx Environment (sandbox or production)
FEDEX_ENVIRONMENT=sandbox

# FedEx OAuth Credentials
FEDEX_CLIENT_ID=your-client-id
FEDEX_CLIENT_SECRET=your-client-secret

# FedEx Account Number
FEDEX_ACCOUNT_NUMBER=your-account-number

# Optional: Label Response Options (URL_ONLY or LABEL)
FEDEX_LABEL_RESPONSE_OPTIONS=URL_ONLY

# Optional: Token Cache TTL in seconds (default: 3500)
FEDEX_TOKEN_CACHE_TTL=3500

Getting FedEx API Credentials

1. Go to FedEx Developer Portal
2. Create an account or sign in
3. Create a new project
4. Generate API credentials (Client ID and Client Secret)
5. Use sandbox credentials for testing and production credentials for live operations

Usage

OAuth Authentication

The package handles OAuth authentication automatically. Tokens are cached to minimize API calls and automatically refreshed when needed.

use SmartDato\FedEx\Fedex;

class ShippingController extends Controller
{
    public function __construct(private Fedex $fedex)
    {
    }

    public function createShipment()
    {
        // The OAuth token is automatically managed
        $result = $this->fedex->createShipment($shipmentPayload);
    }
}

Manual Token Management

If you need to manually manage tokens:

use SmartDato\FedEx\Fedex;

public function __construct(private Fedex $fedex)
{
}

// Force refresh the OAuth token
$newToken = $this->fedex->refreshToken();

// Get the OAuth client directly
$oauthClient = $this->fedex->getOAuthClient();

// Get current access token
$token = $oauthClient->getAccessToken();

// Clear cached token
$oauthClient->clearToken();

Creating a Shipment

use SmartDato\FedEx\Fedex;
use SmartDato\FedEx\Payloads\ShipmentPayload;
use SmartDato\FedEx\Payloads\ShipperPayload;
use SmartDato\FedEx\Payloads\RecipientPayload;
use SmartDato\FedEx\Payloads\AddressPayload;
use SmartDato\FedEx\Payloads\ContactPayload;
use SmartDato\FedEx\Payloads\RequestedPackageLineItemPayload;
use SmartDato\FedEx\Payloads\WeightPayload;
use SmartDato\FedEx\Enums\WeightUnitEnum;
use SmartDato\FedEx\Enums\PackagingTypeEnum;
use SmartDato\FedEx\Enums\PickupTypeEnum;

$shipment = ShipmentPayload::make()
    ->setShipper(
        ShipperPayload::make()
            ->setContact(
                ContactPayload::make()
                    ->setPersonName('John Doe')
                    ->setPhoneNumber('1234567890')
            )
            ->setAddress(
                AddressPayload::make()
                    ->setStreetLines(['123 Main St'])
                    ->setCity('Memphis')
                    ->setStateOrProvinceCode('TN')
                    ->setPostalCode('38115')
                    ->setCountryCode('US')
            )
    )
    ->setRecipient(
        RecipientPayload::make()
            ->setContact(
                ContactPayload::make()
                    ->setPersonName('Jane Smith')
                    ->setPhoneNumber('0987654321')
            )
            ->setAddress(
                AddressPayload::make()
                    ->setStreetLines(['456 Oak Ave'])
                    ->setCity('Los Angeles')
                    ->setStateOrProvinceCode('CA')
                    ->setPostalCode('90001')
                    ->setCountryCode('US')
            )
    )
    ->setRequestedPackageLineItems([
        RequestedPackageLineItemPayload::make()
            ->setWeight(
                WeightPayload::make()
                    ->setValue(10.0)
                    ->setUnits(WeightUnitEnum::LB)
            )
    ])
    ->setPickupType(PickupTypeEnum::DROPOFF_AT_FEDEX_LOCATION)
    ->setPackagingType(PackagingTypeEnum::YOUR_PACKAGING);

// Inject or resolve the Fedex service
$fedex = app(Fedex::class);
$response = $fedex->createShipment($shipment);

Tracking a Shipment

use SmartDato\FedEx\Fedex;
use SmartDato\FedEx\Enums\TrackBy;

// Inject or resolve the Fedex service
$fedex = app(Fedex::class);

// Track by tracking number (default)
$tracking = $fedex->trackShipment('123456789012');

// Track by tracking number with detailed scans
$tracking = $fedex->trackShipment('123456789012', TrackBy::TRACKING_NUMBER, [
    'includeDetailedScans' => true,
]);

// Track by TCN (Tracking Control Number)
$tracking = $fedex->trackShipment('123456789012', TrackBy::TCN);

// Track by reference number with ship date range
$tracking = $fedex->trackShipment('REFERENCE123', TrackBy::REFERENCE_NUMBER, [
    'shipDateBegin' => '2024-01-01',
    'shipDateEnd' => '2024-01-31',
    'includeDetailedScans' => true,
]);

// Track multiple shipments at once
$tracking = $fedex->trackMultipleShipments([
    '123456789012',
    '123456789013',
    '123456789014',
], [
    'includeDetailedScans' => true,
]);

Trade Documents (ETD Upload)

The Trade Documents endpoints are exposed on a dedicated sub-client via Fedex::tradeDocuments(). Three operations are supported: single document upload, multi-document upload (max 5 per call), and letterhead/signature image upload.

Upload a single document (pre or post-shipment)

use SmartDato\FedEx\Fedex;
use SmartDato\FedEx\Enums\CountryEnum;
use SmartDato\FedEx\Enums\EtdContentTypeEnum;
use SmartDato\FedEx\Enums\EtdWorkflowEnum;
use SmartDato\FedEx\Enums\ShipDocumentTypeEnum;
use SmartDato\FedEx\Payloads\EtdMetaPayload;
use SmartDato\FedEx\Payloads\EtdUploadDocumentPayload;

$payload = new EtdUploadDocumentPayload(
    workflowName: EtdWorkflowEnum::PRE_SHIPMENT,
    fileName: 'invoice.pdf',
    contentType: EtdContentTypeEnum::PDF,
    meta: new EtdMetaPayload(
        shipDocumentType: ShipDocumentTypeEnum::COMMERCIAL_INVOICE,
        originCountryCode: CountryEnum::US,
        destinationCountryCode: CountryEnum::CA,
    ),
);

$response = app(Fedex::class)
    ->tradeDocuments()
    ->upload($payload, '/path/to/invoice.pdf');

For post-shipment uploads, also pass carrierCode, trackingNumber, shipmentDate, and the FedEx origin/destination location codes returned by the create-shipment response.

Upload multiple documents in one call

use SmartDato\FedEx\Enums\CarrierCodeEnum;
use SmartDato\FedEx\Payloads\EtdMultiMetaPayload;
use SmartDato\FedEx\Payloads\EtdMultiUploadPayload;

$payload = new EtdMultiUploadPayload(
    workflowName: EtdWorkflowEnum::PRE_SHIPMENT,
    carrierCode: CarrierCodeEnum::FDXE,
    originCountryCode: CountryEnum::US,
    destinationCountryCode: CountryEnum::CA,
    metaData: [
        new EtdMultiMetaPayload(
            fileName: 'invoice.pdf',
            contentType: EtdContentTypeEnum::PDF,
            shipDocumentType: ShipDocumentTypeEnum::COMMERCIAL_INVOICE,
            filePath: '/path/to/invoice.pdf',
            fileReferenceId: 'CI_1',
            formCode: 'USMCA',
        ),
        new EtdMultiMetaPayload(
            fileName: 'origin.pdf',
            contentType: EtdContentTypeEnum::PDF,
            shipDocumentType: ShipDocumentTypeEnum::USMCA_CERTIFICATION_OF_ORIGIN,
            filePath: '/path/to/origin.pdf',
            fileReferenceId: 'CO_1',
            formCode: 'USMCA',
        ),
    ],
);

$response = app(Fedex::class)
    ->tradeDocuments()
    ->uploadMultiple($payload);

A maximum of 5 documents per call is enforced.

Upload a custom letterhead or signature image

use SmartDato\FedEx\Enums\LhsImageContentTypeEnum;
use SmartDato\FedEx\Enums\LhsImageIndexEnum;
use SmartDato\FedEx\Enums\LhsImageTypeEnum;
use SmartDato\FedEx\Payloads\LhsImageUploadPayload;

$payload = new LhsImageUploadPayload(
    referenceId: '1234',
    name: 'signature.png',
    contentType: LhsImageContentTypeEnum::PNG,
    imageType: LhsImageTypeEnum::SIGNATURE,
    imageIndex: LhsImageIndexEnum::IMAGE_1,
);

$response = app(Fedex::class)
    ->tradeDocuments()
    ->uploadLetterheadOrSignature($payload, '/path/to/signature.png');

Each upload method also accepts an optional $customerTransactionId argument that is passed as the x-customer-transaction-id header and echoed back in the response — useful for matching async/multi requests.

All upload methods return the raw Illuminate\Http\Client\Response: decode it with ->json(), or persist the untouched body via ->body()/->status() for request/response logging in the consuming application.

OAuth Token Caching

The package automatically caches OAuth tokens using Laravel's cache system. By default:

• Tokens are cached for 3500 seconds (just under 1 hour)
• Cache key is fedex_oauth_token
• Tokens are automatically refreshed when expired

You can customize these settings in the config file or via environment variables.

Error Handling

use SmartDato\FedEx\Fedex;
use Illuminate\Http\Client\ConnectionException;
use RuntimeException;

$fedex = app(Fedex::class);

try {
    $result = $fedex->createShipment($shipmentPayload);
} catch (ConnectionException $e) {
    // Handle connection errors
    Log::error('FedEx API connection error: ' . $e->getMessage());
} catch (RuntimeException $e) {
    // Handle OAuth or other runtime errors
    Log::error('FedEx API error: ' . $e->getMessage());
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• smart-dato
• All Contributors

License

The MIT License (MIT). Please see License File for more information.