Search by

ktscript / fedex-rest

ktscript

Fedex REST API client for PHP >=7.2.5 through 8.x (incl. 8.4/8.5), Laravel 7-13+, Guzzle 6|7|8

Package info

github.com/ktscript/fedex_rest_api

Chat

pkg:composer/ktscript/fedex-rest

Statistics

Installs: 18 884

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v1.3.1 2026-11-04 06:01 UTC

This package is auto-updated.

Last update: 2026-11-04 06:02:29 UTC


README

PHP package for integrating with FedEx REST API. This package provides a simple and intuitive interface for working with FedEx services including tracking, shipping, and address validation.

Features

  • 🚀 Easy Integration - Simple, fluent API for interacting with FedEx services
  • 🔐 OAuth 2.0 Support - Built-in authorization handling
  • 💵 Rates - Quote rates and transit times
  • 📦 Ship - Create outbound shipments, return tags, cancel shipments
  • 🚚 Pickup - Check availability, schedule and cancel pickups
  • 📍 Address Validation - Validate addresses using FedEx API
  • 📌 Location Search - Find FedEx pickup/dropoff locations by address, coordinates, or phone
  • 🔄 Environment Switching - Switch between sandbox and production environments easily
  • 🎯 Laravel Compatible - Works with Laravel 7–13+ via Conditionable (illuminate/support)
  • 🔧 Fluent Interface - Chainable methods for building requests

Requirements

  • PHP >= 7.2.5 (including PHP 8.0–8.5+)
  • Laravel 7–13+ (or illuminate/support ^7–^13)
  • Guzzle HTTP Client ^6|^7|^8
  • JSON extension

Installation

Install the package via Composer (latest stable release from Packagist):

composer require ktscript/fedex-rest

To pin a version range in composer.json, use a stable constraint:

{
    "require": {
        "ktscript/fedex-rest": "^1.2"
    }
}

Prefer tagged releases over dev-main / @dev so installs resolve to published versions and cold CI counts as a real Packagist download of a release.

Configuration

Getting FedEx API Credentials

  1. Register for a FedEx Developer account at FedEx Developer Portal
  2. Create a new application to get your client_id and client_secret
  3. Choose between sandbox (testing) or production environment

Usage

Authorization

First, you need to obtain an access token using your FedEx credentials:

use FedexRest\Authorization\Authorize;

$authorize = new Authorize();
$authorize->setClientId('your_client_id')
    ->setClientSecret('your_client_secret')
    ->useProduction() // Use production environment (optional, defaults to sandbox)
    ->authorize();

$token = $authorize->access_token;

Tracking Packages

Track one or multiple packages by tracking number:

use FedexRest\Services\Track\TrackByTrackingNumberRequest;

$tracking = new TrackByTrackingNumberRequest();
$tracking->setAccessToken($token)
    ->setTrackingNumber('1234567890') // Single tracking number
    ->includeDetailedScans() // Optional: include detailed scan information
    ->useProduction() // Optional: use production environment
    ->request();

// Or track multiple packages
$tracking->setTrackingNumber(['1234567890', '0987654321'])
    ->request();

Rate Quotes

use FedexRest\Services\Rate\RateRequest;
use FedexRest\Entity\Person;
use FedexRest\Entity\Address;
use FedexRest\Entity\Item;
use FedexRest\Entity\Weight;
use FedexRest\Services\Ship\Type\PickupType;

$shipperAddress = (new Address())
    ->setPostalCode('38116')
    ->setCountryCode('US');
$recipientAddress = (new Address())
    ->setPostalCode('90001')
    ->setCountryCode('US');

$weight = (new Weight())->setUnit('LB')->setValue(5);
$item = (new Item())->setItemDescription('Sample Product')->setWeight($weight);

$rate = new RateRequest();
$rate->setAccessToken($token)
    ->setAccountNumber('123456789')
    ->setShipper((new Person())->withAddress($shipperAddress))
    ->setRecipient((new Person())->withAddress($recipientAddress))
    ->setPickupType(PickupType::_DROPOFF_AT_FEDEX_LOCATION)
    ->setLineItems($item)
    ->request();

Create Outbound Shipment

Standard ship (not a return tag). Uses POST /ship/v1/shipments without RETURN_SHIPMENT.

use FedexRest\Services\Ship\CreateShipmentRequest;
use FedexRest\Entity\Person;
use FedexRest\Entity\Address;
use FedexRest\Entity\Item;
use FedexRest\Entity\Weight;
use FedexRest\Services\Ship\Type\ServiceType;
use FedexRest\Services\Ship\Type\PackagingType;
use FedexRest\Services\Ship\Type\PickupType;

$shipperAddress = (new Address())
    ->setStreetLines('123 Main St')
    ->setCity('Memphis')
    ->setStateOrProvince('TN')
    ->setPostalCode('38116')
    ->setCountryCode('US');
$shipper = (new Person())
    ->setPersonName('John Doe')
    ->setPhoneNumber(1234567890)
    ->withAddress($shipperAddress);

$recipientAddress = (new Address())
    ->setStreetLines('456 Oak Ave')
    ->setCity('Los Angeles')
    ->setStateOrProvince('CA')
    ->setPostalCode('90001')
    ->setCountryCode('US');
$recipient = (new Person())
    ->setPersonName('Jane Smith')
    ->setPhoneNumber(9876543210)
    ->withAddress($recipientAddress);

$item = (new Item())
    ->setItemDescription('Sample Product')
    ->setWeight((new Weight())->setUnit('LB')->setValue(5));

$shipment = new CreateShipmentRequest();
$shipment->setAccessToken($token)
    ->setAccountNumber('123456789')
    ->setShipper($shipper)
    ->setRecipients($recipient)
    ->setLineItems($item)
    ->setServiceType(ServiceType::_FEDEX_GROUND)
    ->setPackagingType(PackagingType::_YOUR_PACKAGING)
    ->setPickupType(PickupType::_USE_SCHEDULED_PICKUP)
    ->setShipDatestamp('2026-11-05')
    ->request();

Cancel Shipment

use FedexRest\Services\Ship\CancelShipmentRequest;

$cancel = new CancelShipmentRequest();
$cancel->setAccessToken($token)
    ->setAccountNumber('123456789')
    ->setTrackingNumber('794612345678')
    ->setSenderCountryCode('US')
    ->request();

Create Return Tag (print return label)

CreateTagRequest still creates a return label (RETURN_SHIPMENT / PRINT_RETURN_LABEL).

use FedexRest\Services\Ship\CreateTagRequest;
use FedexRest\Entity\Person;
use FedexRest\Entity\Address;
use FedexRest\Entity\Item;
use FedexRest\Entity\Weight;
use FedexRest\Services\Ship\Type\ServiceType;
use FedexRest\Services\Ship\Type\PackagingType;
use FedexRest\Services\Ship\Type\PickupType;

$shipperAddress = (new Address())
    ->setStreetLines('123 Main St')
    ->setCity('Memphis')
    ->setStateOrProvince('TN')
    ->setPostalCode('38116')
    ->setCountryCode('US');
$shipper = (new Person())
    ->setPersonName('John Doe')
    ->setPhoneNumber(1234567890)
    ->withAddress($shipperAddress);

$recipientAddress = (new Address())
    ->setStreetLines('456 Oak Ave')
    ->setCity('Los Angeles')
    ->setStateOrProvince('CA')
    ->setPostalCode('90001')
    ->setCountryCode('US');
$recipient = (new Person())
    ->setPersonName('Jane Smith')
    ->setPhoneNumber(9876543210)
    ->withAddress($recipientAddress);

$item = (new Item())
    ->setItemDescription('Sample Product')
    ->setWeight((new Weight())->setUnit('LB')->setValue(5));

$shipment = new CreateTagRequest();
$shipment->setAccessToken($token)
    ->setAccountNumber(123456789)
    ->setShipper($shipper)
    ->setRecipients($recipient)
    ->setLineItems($item)
    ->setServiceType(ServiceType::_FEDEX_GROUND)
    ->setPackagingType(PackagingType::_FEDEX_BOX)
    ->setPickupType(PickupType::_USE_SCHEDULED_PICKUP)
    ->setShipDatestamp('2024-01-15')
    ->useProduction()
    ->request();

Pickup Availability / Create / Cancel

use FedexRest\Services\Pickup\PickupAvailabilityRequest;
use FedexRest\Services\Pickup\CreatePickupRequest;
use FedexRest\Services\Pickup\CancelPickupRequest;
use FedexRest\Services\Pickup\Type\CarrierCodeType;
use FedexRest\Entity\Address;
use FedexRest\Entity\Person;

$address = (new Address())
    ->setStreetLines('123 Main St')
    ->setCity('Memphis')
    ->setStateOrProvince('TN')
    ->setPostalCode('38116')
    ->setCountryCode('US');

$availability = new PickupAvailabilityRequest();
$availability->setAccessToken($token)
    ->setPickupAddress($address)
    ->setCarriers([CarrierCodeType::FDXE])
    ->setDispatchDate('2026-11-05')
    ->setPackageReadyTime('09:00:00')
    ->setCustomerCloseTime('17:00:00')
    ->request();

$pickupPerson = (new Person())
    ->setPersonName('John Doe')
    ->setPhoneNumber(1234567890)
    ->withAddress($address);

$pickup = new CreatePickupRequest();
$pickup->setAccessToken($token)
    ->setAccountNumber('123456789')
    ->setPickupLocation($pickupPerson)
    ->setReadyDateTimestamp('2026-11-05T09:00:00')
    ->setCustomerCloseTime('17:00:00')
    ->setCarrierCode(CarrierCodeType::FDXE)
    ->request();

$cancelPickup = new CancelPickupRequest();
$cancelPickup->setAccessToken($token)
    ->setAccountNumber('123456789')
    ->setPickupConfirmationCode('CONFIRMATION')
    ->setScheduledDate('2026-11-05')
    ->setLocation('NQAA')
    ->setCarrierCode(CarrierCodeType::FDXE)
    ->request();

Address Validation

Validate addresses using FedEx address validation service:

use FedexRest\Services\AddressValidation\AddressValidation;
use FedexRest\Entity\Address;

$address = new Address();
$address->setStreetLines('123 Main St')
    ->setCity('Memphis')
    ->setStateOrProvince('TN')
    ->setPostalCode('38116')
    ->setCountryCode('US');

$validation = new AddressValidation();
$validation->setAccessToken($token)
    ->setAddress($address)
    ->useProduction() // Optional: use production environment
    ->request();

Location Search (FedEx Location API)

Search for FedEx pickup and dropoff locations by address, coordinates, or phone:

use FedexRest\Services\Location\LocationSearchRequest;
use FedexRest\Services\Location\Type\LocationType;
use FedexRest\Entity\Address;

// Search by address
$address = new Address();
$address->setStreetLines('123 Main St')
    ->setCity('Memphis')
    ->setStateOrProvince('TN')
    ->setPostalCode('38116')
    ->setCountryCode('US');

$locationSearch = new LocationSearchRequest();
$result = $locationSearch->setAccessToken($token)
    ->setAddress($address)
    ->setDistance(10, LocationSearchRequest::UNITS_KM)
    ->setLocationTypes([LocationType::FEDEX_OFFICE, LocationType::FEDEX_SELF_SERVICE_LOCATION])
    ->setResultsLimit(15)
    ->useProduction()
    ->request();

// Or search by coordinates
$result = $locationSearch->setAccessToken($token)
    ->setCoordinates(35.1495, -90.0490)
    ->setDistance(5, LocationSearchRequest::UNITS_MI)
    ->request();

// Or search by phone number
$result = $locationSearch->setAccessToken($token)
    ->setPhoneNumber('9015551234')
    ->request();

The response is a decoded object. Main keys:

  • output.totalResults, output.resultsReturned — count of locations
  • output.locationDetailList — array of locations (each has distance, contactAndAddress with address/contact/displayName, locationId, storeHours, carrierDetailList, locationType, locationCapabilities, etc.)
  • output.nearestLocation, output.latestLocation — single location objects when applicable
  • output.matchedAddress — normalized search address
  • output.alerts — optional messages

Environment Switching

The package supports easy switching between sandbox (testing) and production environments:

// Use sandbox (default)
$request->request();

// Use production
$request->useProduction()->request();

// Using Laravel's Conditionable trait (when available)
$request->when($isProduction, fn($req) => $req->useProduction())
    ->request();

Raw Response

Get raw HTTP response instead of decoded JSON:

$response = $request->asRaw()->request();
// Returns GuzzleHttp\Psr7\Response object

Available Service Types

Use constants from FedexRest\Services\Ship\Type\ServiceType:

  • ServiceType::_FEDEX_GROUND
  • ServiceType::_FEDEX_2_DAY
  • ServiceType::_STANDARD_OVERNIGHT
  • ServiceType::_PRIORITY_OVERNIGHT
  • ServiceType::_INTERNATIONAL_PRIORITY
  • And many more...

Available Packaging Types

Use constants from FedexRest\Services\Ship\Type\PackagingType:

  • PackagingType::_YOUR_PACKAGING
  • PackagingType::_FEDEX_BOX
  • PackagingType::_FEDEX_ENVELOPE
  • PackagingType::_FEDEX_PAK
  • And more...

Available Pickup Types

Use constants from FedexRest\Services\Ship\Type\PickupType:

  • PickupType::_USE_SCHEDULED_PICKUP
  • PickupType::_DROPOFF_AT_FEDEX_LOCATION
  • PickupType::_CONTACT_FEDEX_TO_SCHEDULE

Exception Handling

The package throws specific exceptions for missing required data:

  • MissingAccessTokenException - When access token is not provided
  • MissingAuthCredentialsException - When client credentials are missing
  • MissingTrackingNumberException - When tracking number is not provided
  • MissingAccountNumberException - When account number is missing
  • MissingLineItemException - When line items are not provided
  • MissingPickupConfirmationCodeException - When pickup confirmation code is missing
use FedexRest\Exceptions\MissingAccessTokenException;

try {
    $response = $request->request();
} catch (MissingAccessTokenException $e) {
    // Handle missing access token
}

Advanced Usage

Custom Request Parameters

For shipping labels, you can customize request parameters:

$shipment = new CreateTagRequest();
$params = $shipment->getRequestParams();
// Modify $params array as needed
$shipment->setRequestParams($params)
    ->setAccessToken($token)
    ->request();

Laravel Integration

This package works with Laravel 7–13+. The switchableEnv trait uses Laravel's Conditionable trait, allowing you to use the when() method:

use FedexRest\Services\Track\TrackByTrackingNumberRequest;

$tracking = new TrackByTrackingNumberRequest();
$tracking->setAccessToken($token)
    ->setTrackingNumber('1234567890')
    ->when(config('app.env') === 'production', fn($req) => $req->useProduction())
    ->request();

Support

For issues, questions, or contributions, please visit:

License

This package is open-sourced software licensed under the MIT license.

Credits

Special thanks to Sinnbeck for the help and contributions.

Changelog

1.3.1

  • Declare support for PHP 8.x through latest (8.4/8.5+), Laravel 13 (illuminate/support ^13), Guzzle 8
  • Fix exception constructors for PHP 8.4+ nullable Throwable $previous

1.3.0

  • Rates and Transit Times: RateRequest (POST /rate/v1/rates/quotes)
  • Ship: CreateShipmentRequest (outbound, no return special service)
  • Ship: CancelShipmentRequest (PUT /ship/v1/shipments/cancel)
  • Pickup: PickupAvailabilityRequest, CreatePickupRequest, CancelPickupRequest
  • Clarify that CreateTagRequest remains return-tag only

1.2.1-1.2.5

  • Fix Location API
  • Add LocationType constants
  • Add LocationSearchRequest
  • Add LocationSearchResponse
  • Add LocationSearchResponseItem

1.2.0

  • FedEx Location API: search pickup/dropoff locations by address, coordinates, or phone
  • LocationSearchRequest and LocationType constants
  • Support contact: Telegram @ktscript added to README and composer.json

1.0.0

  • Initial stable release
  • Support for Laravel 7-13+ / PHP 8.x
  • OAuth 2.0 authorization
  • Package tracking
  • Shipping label creation
  • Address validation
  • Environment switching (sandbox/production)
  • Fluent interface with method chaining