FEDEXv3 REST Shipping Rates

1. Overview

Jscriptz FEDEXv3 is a modern FedEx shipping integration for Magento 2 that uses the new FedEx REST APIs with OAuth2 authentication. This module provides real-time shipping rates, transit time information, and address validation capabilities.

2. Features

Shipping Rates

• OAuth2 Authentication: Secure token-based authentication with automatic token refresh
• Real-Time Shipping Rates: Get accurate, up-to-date rates from FedEx
• Transit Time Information: Show estimated delivery dates with shipping methods
• Rate Caching: Cache rates to reduce API calls and improve performance
• Fallback Support: Return cached rates if FedEx API is temporarily unavailable
• Address Validation: Validate shipping addresses using FedEx API (optional)
• Residential Detection: Automatic residential/commercial address detection
• Handling Fees: Add a flat handling fee to all shipping rates
• Free Shipping Threshold: Offer free shipping above a cart subtotal

Label Generation

• Create Labels from Admin: Generate FedEx shipping labels directly from shipment view
• Multiple Label Formats: Support for PDF, PNG, ZPLII, and EPL2 formats
• Automatic Tracking: Tracking number automatically added to shipment
• View & Download: View labels in browser or download files
• Configurable Shipper Address: Set your return address in configuration
• Default Package Dimensions: Configure default weight and dimensions

Webhook Tracking

• Real-Time Updates: Receive tracking events from FedEx via webhooks
• HMAC Signature Validation: Secure webhook verification
• Event Deduplication: Prevent duplicate events from being stored
• Automatic Email Notifications: Send customers tracking update emails
• POD Photo Support: Include proof of delivery photos in emails
• Configurable Events: Choose which events trigger customer emails

Tracking History Display

• Admin Timeline: Color-coded tracking timeline on shipment view
• Customer Timeline: Tracking history on customer order pages
• Status Badges: Visual status indicators (Delivered, In Transit, etc.)
• Location Tracking: City, state, and country for each event
• Signature Proof: Display signature name for delivered packages
• FedEx.com Link: Direct links to FedEx tracking page

Developer Features

• Sandbox Mode: Test your integration before going live
• Debug Logging: Detailed logging for troubleshooting
• Event Storage: Raw webhook payloads stored for debugging

3. Requirements

• Magento 2.4.x
• PHP 8.1 or higher
• FedEx Developer Account (free)
• FedEx Account Number (for production rates)

4. Installation

Prerequisites

• Magento 2.4.4 or higher
• PHP 8.1 or higher
• Composer 2.x
• Valid Jscriptz license (purchased from mage.jscriptz.com)

1 Get Your Composer Access Token

After purchasing the extension, log in to your Jscriptz account to get your Composer authentication token:

1. Go to mage.jscriptz.com/customer/account
2. Click on GitHub Access in the left sidebar
3. Click Generate New Token if you don't have one
4. Copy your access token (it will look like a long string of characters)

2 Configure Composer Authentication

Create or update your auth.json file in your Magento root directory:

{
    "http-basic": {
        "packages.jscriptz.com": {
            "username": "YOUR_LICENSE_KEY",
            "password": "YOUR_ACCESS_TOKEN"
        }
    }
}

Replace:

• YOUR_LICENSE_KEY - Your license key from My Licenses page
• YOUR_ACCESS_TOKEN - The token you copied in Step 1

3 Add Repository & Install Package

Add the Jscriptz package repository and install the module:

# Add the Jscriptz repository (first time only)
composer config repositories.jscriptz composer https://packages.jscriptz.com

# Install FEDEXv3 (includes ShippingCore dependency)
composer require jscriptz/module-fedexv3

4 Run Magento Setup

# Enable the modules
bin/magento module:enable Jscriptz_ShippingCore Jscriptz_FEDEXv3

# Run setup upgrade
bin/magento setup:upgrade

# Compile DI (production mode)
bin/magento setup:di:compile

# Deploy static content (production mode)
bin/magento setup:static-content:deploy -f

# Clear cache
bin/magento cache:flush

5 Activate Your License

After installation, you need to activate your license in the Magento admin:

1. Go to Stores → Configuration → Sales → Shipping Methods → Jscriptz FEDEXv3
2. Expand the License section
3. Enter your License Key from your Jscriptz License Account
4. Click Save Config
5. Click Verify License to confirm your license is active

5. FedEx Developer Portal Setup

Before configuring the module in Magento, you need to create an API project in the FedEx Developer Portal to obtain your API credentials.

1 Create a FedEx Developer Account

Visit developer.fedex.com and create a free developer account if you don't already have one.

2 Create a New Project

After logging in, navigate to My Projects and click + CREATE PROJECT. You'll be asked to tell FedEx about your API needs.

3 Select Company Type

Choose the option that best describes your business. For most e-commerce stores, select "Ships using FedEx different than the options listed" or the appropriate shipping option.

4 Select APIs for Your Project

On the API selection page, you'll see all available FedEx APIs. For this module, select the following:

• Rates and Transit Times API - Required for shipping rates
• Address Validation API - Optional, for address verification

5 Configure Your Project

Enter a name for your project (e.g., "Magento_FEDEXv3") and select your shipping country. Choose United States for a Global test account.

6 Accept Terms and Create Project

Review your project details, accept the terms and conditions, and click CREATE to generate your API credentials.

7 Retrieve Your API Credentials

After your project is created, you'll see your API credentials on the project overview page. You'll need:

• API Key (also called Client ID)
• Secret Key (also called Client Secret)
• Account Number (shown in the credentials table)

6. Magento Configuration

Configure the module in the Magento Admin at:

Stores > Configuration > Jscriptz > Jscriptz FEDEXv3

General Settings

API Credentials

Shipping Options

Rate Caching

Address Validation

Shipping Restrictions

Label Generation

Shipper Address

Configure the return address used on shipping labels.

Webhook Configuration

Developer Settings

7. Label Generation

Create FedEx shipping labels directly from the Magento Admin without leaving your store.

Creating a Shipping Label

1. Navigate to Sales > Orders and select an order
2. Click Ship to create a shipment (or view an existing shipment)
3. On the shipment view page, find the FedEx Shipping Label section
4. Click Create Shipping Label
5. The label will be generated and the tracking number automatically added

Label Formats

Requirements

• Shipper address must be fully configured in module settings
• Your FedEx account must have Ship API access enabled
• The order must have a valid shipping address

8. Webhook Tracking

Receive real-time tracking updates from FedEx as packages move through the delivery network.

How It Works

1. When you create a shipping label, FedEx begins tracking the package
2. As the package status changes, FedEx sends webhook notifications to your store
3. The module validates and stores each tracking event
4. Customers receive email notifications based on your configuration
5. Tracking history displays in admin and customer views

Webhook URL

Configure this URL in the FedEx Developer Portal to receive tracking updates:

https://your-store.com/fedexv3/webhook/receive

Setting Up Webhooks in FedEx Portal

1. Log in to developer.fedex.com
2. Navigate to your project and find Webhooks settings
3. Add a new webhook subscription for Track API events
4. Enter your store's webhook URL
5. Copy the Security Token (HMAC secret) provided by FedEx
6. Enter the security token in your Magento configuration

Tracking Event Types

Email Notifications

Configure which events trigger customer email notifications. You can choose to notify customers for:

• All tracking events (leave selection empty)
• Specific events only (e.g., only out_for_delivery and delivered)

9. Tracking History Display

View complete tracking timelines in both admin and customer-facing pages.

Admin Tracking History

Navigate to Sales > Shipments > View Shipment to see the tracking timeline.

The admin view includes:

• FedEx logo header with purple branding
• Color-coded status badges for each event
• Event timestamp and description
• Location (city, state, country) with map pin icon
• Event code for debugging purposes
• Signature proof for delivered packages
• POD photos when available

Customer Tracking History

Customers view tracking from My Account > My Orders > View Order > Order Shipments.

The customer view includes:

• Current status banner at the top
• Clickable tracking number linking to FedEx.com
• Complete timeline with all tracking events
• Color-coded badges matching the admin view
• Location information for each event
• Signature proof when available
• Mobile-responsive design

10. Customer Preferences

Customers can manage their shipping notification preferences from their account.

Shipping Notifications Page

Customers access preferences at: My Account > Shipping Notifications

URL: /fedexv3/customer/shippingPreferences/

Available Preferences

11. Testing

Sandbox Testing

1. Set Environment to Sandbox
2. Use your Test Key credentials from the FedEx Developer Portal
3. Add a product to cart and proceed to checkout
4. Enter a valid US shipping address
5. FedEx shipping methods should appear with rates

Debug Mode

Enable Debug Mode to log detailed API information:

1. Set Debug Mode to Yes
2. View logs at var/log/system.log
3. Look for entries prefixed with [FEDEXv3]

# View FEDEXv3 debug logs
tail -f var/log/system.log | grep "FEDEXv3"

Production Testing

1. Switch to Production environment
2. Enter your Production Key credentials
3. Clear Magento cache
4. Test checkout with real shipping addresses
5. Verify rates match your FedEx account pricing

11b. Webhook Simulator (Sandbox Testing)

The Webhook Simulator allows you to test FedEx webhook integrations without real shipments. This is essential for verifying that tracking updates and customer email notifications work correctly before going live.

What You Can Test

• Webhook Processing: Verify your store correctly receives and processes tracking events
• Email Notifications: Confirm customers receive tracking update emails with correct content
• Tracking Display: Check that tracking history appears correctly in admin and customer account
• POD Photos: Test proof of delivery photo display in emails and tracking history
• Debug Integrations: Identify issues before enabling production webhooks

Requirements

The webhook simulator is only available when all three conditions are met:

1. Carrier in Sandbox Mode: FEDEXv3 must be set to Sandbox environment
2. Webhook Tracking Enabled: The webhook tracking feature must be turned on
3. Simulator Enabled: The global webhook simulator setting must be enabled in ShippingCore

Enabling the Simulator

Step 1: Enable the Webhook Simulator in ShippingCore

Navigate to: Stores > Configuration > Jscriptz > Shipping Preferences

Scroll to the Webhook Testing (Sandbox) section and set Enable Webhook Simulator to Yes.

Step 2: Configure FEDEXv3 for Sandbox + Webhooks

Navigate to: Stores > Configuration > Jscriptz > Jscriptz FEDEXv3

1. Set Environment to Sandbox (Testing)
2. Set Enable Webhook Tracking to Yes
3. Save configuration and clear cache

Using the Simulator

Accessing the Simulator Interface

1. Navigate to: Stores > Configuration > Jscriptz > Shipping Preferences
2. Scroll to the Webhook Testing (Sandbox) section
3. The simulator interface appears below the enable toggle

Simulator Fields

Available FedEx Event Types

Running a Simulation

1. Select Carrier: Choose "FedEx" from the carrier dropdown
2. Select Event Type: Pick the tracking event to simulate (e.g., "Delivered")
3. Enter Tracking Number (Optional):
   • Leave empty to generate a mock tracking number
   • Enter a real tracking number from an existing shipment for realistic testing
4. Click "Send Test Webhook"

Testing with Real Shipment Data

For the most realistic testing, use a tracking number from an existing shipment:

1. Go to Sales > Shipments
2. Find a shipment with a FedEx tracking number
3. Copy the tracking number
4. Paste it into the simulator's tracking number field
5. Select an event type and click "Send Test Webhook"

This allows you to:

• See tracking events appear on the real shipment's tracking history
• Test that emails are sent to the actual customer email address
• Verify the admin tracking history display with real order data
• Test the customer-facing tracking page with real shipment context

Verifying Simulation Results

Check Tracking History in Admin

1. Navigate to Sales > Shipments
2. Find and view the shipment with the simulated tracking number
3. Scroll to the FedEx Tracking History section
4. Verify the simulated event appears with correct status badge, location, and timestamp

Check Email Delivery

• Email Logs: If using an email logging extension, check for the tracking notification
• Mailhog/Mailtrap: If using a development mail catcher, verify the email content
• Customer Email: If testing with real customer data, check their inbox

Check Database

Events are stored in the jscriptz_fedexv3_tracking_event table:

SELECT * FROM jscriptz_fedexv3_tracking_event
WHERE tracking_number = 'YOUR_TRACKING_NUMBER'
ORDER BY created_at DESC;

Troubleshooting Simulator Issues

FedEx Not Appearing in Carrier Dropdown

Problem: FedEx doesn't appear in the carrier dropdown.

Solution: Verify both conditions are met:

1. FEDEXv3 Environment is set to Sandbox
2. FEDEXv3 Webhook Tracking is Enabled
3. Run bin/magento setup:di:compile if recently installed
4. Clear all caches: bin/magento cache:flush

"Send Test Webhook" Button Disabled

Problem: The button is disabled and you can't send a test.

Solution:

• Select both a carrier AND an event type
• Ensure the webhook simulator is set to "Yes"

No Email Received After Simulation

Problem: Simulation runs but no email is sent.

Solution:

1. Check FEDEXv3's "Customer Email Notifications" setting - verify the simulated event type triggers emails
2. Verify Magento's email configuration and mail server settings
3. Review var/log/system.log for email errors
4. Query the database to check if email_sent = 1 for the event

Tracking Event Not Appearing in Admin

Problem: Simulation runs but tracking event doesn't appear in admin.

Solution:

1. Clear Magento cache: bin/magento cache:clean
2. Check var/log/system.log for processing errors
3. Verify the tracking number matches an existing shipment track
4. Check the database table directly for the event record

Best Practices

• Test Complete Journey: Simulate the full shipment journey (Label Created → Picked Up → In Transit → Out for Delivery → Delivered)
• Test Exceptions: Simulate exception events (DE, SE) to verify error notifications work correctly
• Use Real Tracking Numbers: Test with actual shipment data for the most realistic results
• Verify Email Templates: Check that email content looks correct for each event type
• Test Customer View: Log in as a customer to verify tracking appears correctly in their order history
• Test Before Production: Always test thoroughly in sandbox before enabling production webhooks

12. Supported Services

Domestic Services (US)

International Services

Package Types

13. Troubleshooting

No Shipping Methods Displayed

1. Verify the module is enabled in configuration
2. Check that API credentials are entered correctly
3. Ensure origin address is configured in Shipping Settings
4. Enable Debug Mode and check system.log for errors
5. Verify the destination country is allowed

Authentication Errors

Solution:

• Re-enter credentials through the Magento Admin (not CLI)
• Verify you're using the correct environment (Sandbox vs Production)
• Check that your FedEx Developer account is active
• Ensure the API project has the Rates API enabled

Rate Parsing Errors

Solution: Update to the latest module version. This issue was fixed in v1.0.0.

Caching Issues

If rates seem outdated:

1. Clear Magento cache: bin/magento cache:flush
2. Reduce Cache TTL in configuration
3. Temporarily disable caching for testing

Missing Transit Times

Transit times come from the FedEx Rate API response. If not displayed:

• Enable Debug Mode and check if transit data is in the response
• Ensure the Jscriptz_Checkout module is installed (for transit time display)
• Some services may not include transit times in sandbox mode

14. FAQ

Can I use this alongside Magento's built-in FedEx module?

Yes, Jscriptz FEDEXv3 uses the carrier code fedexv3 and operates independently of Magento's core FedEx module (fedex). You can run both simultaneously, though we recommend disabling the core module to avoid customer confusion.

Do I need a FedEx business account?

For sandbox testing, you can use the test account number provided by FedEx. For production, you'll need a FedEx account number to get accurate negotiated rates.

Why are my production rates different from sandbox rates?

Sandbox rates are generic list rates for testing purposes. Production rates reflect your actual negotiated pricing with FedEx based on your shipping volume and account agreement.

How often should I refresh cached rates?

The default TTL of 3600 seconds (1 hour) works well for most stores. If your rates change frequently or you need more accuracy, reduce this value. For high-traffic stores, consider keeping caching enabled to reduce API calls.

Can I offer free shipping for FedEx methods?

Yes, set a Free Shipping Threshold amount. When the cart subtotal exceeds this amount, all FedEx rates will show as $0.00.

How do I get negotiated rates?

Ensure your FedEx Account Number is entered in the configuration. Negotiated rates are automatically returned when you have an account with special pricing agreements.

What's the difference between Ground and Home Delivery?

FedEx Ground is for business addresses, while FedEx Home Delivery is for residential addresses. The module automatically detects address type based on whether a company name is provided.

15. ShippingCore Integration

FEDEXv3 integrates with the Jscriptz_ShippingCore companion module to provide enhanced admin and checkout features including an enhanced shipments grid, mass actions, carrier logos, transit time badges, delivery preferences, and dark mode support.

Enhanced Shipments Grid

ShippingCore extends the Sales > Shipments grid with additional columns and mass actions for streamlined shipping management.

Additional Columns

Mass Actions

• Send Tracking Info: Bulk send tracking emails to customers for selected shipments
• Create Shipping Label: Generate labels for multiple shipments at once
  • Combined PDF: All labels merged into a single file
  • ZIP of Separate PDFs: Individual label files in a downloadable archive
• Create Label + Send Tracking: Combined workflow for maximum efficiency

For complete shipments grid documentation, see the ShippingCore User Guide.

Carrier Logo Display

Replace plain text carrier names with official branded logos at checkout for a more professional appearance.

The carrier logo feature:

• Official Logos: Uses official FedEx, UPS, and USPS SVG logos for crisp display at any size
• Toggle Option: Choose between "Show Logo" or "Show Text" in admin configuration
• Auto-Detection: Automatically detects carrier from method code (fedexv3, upsv3, uspsv3)
• Accessible: Logos include ARIA labels for screen reader accessibility

Transit Time Badges

Help customers quickly identify the best shipping option with visual badges.

Cutoff Countdown Colors

The countdown timer changes color based on urgency:

Delivery Preferences Widget

Allow customers to specify delivery requirements directly at checkout.

Signature Options

• No Signature Required: Standard delivery, no signature needed
• Direct Signature: Signature from anyone at the address
• Adult Signature Required: Signature from adult 21+ with ID

Delivery Location Options

• Front Door / Front Porch
• Back Door / Back Porch
• Side Door
• Garage
• Carport
• Mailroom / Mail Center
• Concierge / Front Desk

Display Options

Configure where the delivery preferences widget appears:

• Shipping Methods: After shipping method selection (default)
• Shipping Address: Before the address form
• Payment Step: On the payment page

Dark Mode Support

ShippingCore components automatically adapt to the user's system dark mode preference when enabled. This includes:

• Transit time badges and delivery dates
• Delivery preferences widget
• Cutoff countdown timer
• Carrier logos (with appropriate contrast)

Customer Account Preferences

Customers can save their default delivery preferences in their account:

My Account > Delivery Preferences

• Default Signature Option: Pre-selected signature requirement for all orders
• Preferred Delivery Location: Where to leave packages
• POD Photo Opt-Out: Disable proof of delivery photos in emails

Admin Configuration

Configure ShippingCore features at:

Stores > Configuration > Jscriptz > Shipping Preferences

General Settings

Signature Required Options

Delivery Location Options

Transit Time Display