ktscript / fedex-rest
Fedex REST API client for PHP >=7.2.5 through 8.x (incl. 8.4/8.5), Laravel 7-13+, Guzzle 6|7|8
Requires
- php: >=7.2.5
- ext-json: *
- guzzlehttp/guzzle: ^6|^7|^8
- illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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
- Register for a FedEx Developer account at FedEx Developer Portal
- Create a new application to get your
client_idandclient_secret - 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 locationsoutput.locationDetailList— array of locations (each hasdistance,contactAndAddresswithaddress/contact/displayName,locationId,storeHours,carrierDetailList,locationType,locationCapabilities, etc.)output.nearestLocation,output.latestLocation— single location objects when applicableoutput.matchedAddress— normalized search addressoutput.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_GROUNDServiceType::_FEDEX_2_DAYServiceType::_STANDARD_OVERNIGHTServiceType::_PRIORITY_OVERNIGHTServiceType::_INTERNATIONAL_PRIORITY- And many more...
Available Packaging Types
Use constants from FedexRest\Services\Ship\Type\PackagingType:
PackagingType::_YOUR_PACKAGINGPackagingType::_FEDEX_BOXPackagingType::_FEDEX_ENVELOPEPackagingType::_FEDEX_PAK- And more...
Available Pickup Types
Use constants from FedexRest\Services\Ship\Type\PickupType:
PickupType::_USE_SCHEDULED_PICKUPPickupType::_DROPOFF_AT_FEDEX_LOCATIONPickupType::_CONTACT_FEDEX_TO_SCHEDULE
Exception Handling
The package throws specific exceptions for missing required data:
MissingAccessTokenException- When access token is not providedMissingAuthCredentialsException- When client credentials are missingMissingTrackingNumberException- When tracking number is not providedMissingAccountNumberException- When account number is missingMissingLineItemException- When line items are not providedMissingPickupConfirmationCodeException- 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:
- GitHub Issues
- Telegram: @ktscript — contact the author
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
CreateTagRequestremains return-tag only
1.2.1-1.2.5
- Fix Location API
- Add
LocationTypeconstants - Add
LocationSearchRequest - Add
LocationSearchResponse - Add
LocationSearchResponseItem
1.2.0
- FedEx Location API: search pickup/dropoff locations by address, coordinates, or phone
LocationSearchRequestandLocationTypeconstants- 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