DEV Community

Branden Thomas
Branden Thomas

Posted on • Originally published at toweringmedia.com

Migrating from FedEx SOAP to REST API in Magento 2: A Step-by-Step Guide

#magento #php #ecommerce #fedex

FedEx is retiring the legacy Web Services (SOAP) endpoints that Magento's original carrier integration relied on. If your store still calculates rates through the old Fedex carrier model, you are one FedEx policy change away from blank shipping quotes at checkout.

At Towering Media, we have migrated dozens of Magento 2 and Adobe Commerce stores onto FedEx REST with OAuth 2.0. This guide walks through what changed, how to audit your store, and the migration path we use in production.

Why the SOAP integration is a liability

Magento 2 shipped with a FedEx carrier that calls FedEx Web Services over SOAP. That stack worked for years, but FedEx has been pushing merchants toward the FedEx Developer Portal and REST APIs with client-credentials OAuth.

SOAP failures tend to show up suddenly:

  • Rates return empty arrays with no admin-visible error
  • Tracking requests fail silently on the frontend
  • Label generation breaks during peak season when FedEx throttles legacy endpoints

REST is not a cosmetic upgrade. It uses different request shapes, authentication, and error codes. Treat this as a carrier re-integration, not a version bump.

Step 1: Inventory your current FedEx touchpoints

Before writing code, map every place FedEx appears:

  1. Stores → Configuration → Sales → Delivery Methods → FedEx — core carrier settings
  2. Custom modules — search your codebase for Fedex, fedex, web services, and RateService
  3. Third-party extensions — multi-vendor dropship, ERP connectors, and WMS integrations often wrap the legacy API
  4. Cron and CLI jobs — batch label or tracking jobs may hardcode SOAP WSDL URLs

Run this from your Magento root:

grep -ri "fedex" app/code vendor/your-namespace --include="*.php" --include="*.xml"
Enter fullscreen mode Exit fullscreen mode

Document which environments (production, staging) have active FedEx accounts. SOAP and REST use different API keys.

Step 2: Create FedEx REST credentials

In the FedEx Developer Portal:

  1. Create a project (or use your existing organization)
  2. Enable Rates and Transit Times API and Ship API (if you print labels from Magento)
  3. Generate API Key, Secret Key, and note your Account Number and Meter Number (if applicable to your contract)
  4. Use the sandbox environment first; production credentials are separate

OAuth uses the client credentials grant:

POST https://apis-sandbox.fedex.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_KEY&client_secret=YOUR_SECRET
Enter fullscreen mode Exit fullscreen mode

The response includes a short-lived access_token. Production uses https://apis.fedex.com/oauth/token.

Step 3: Choose your Magento implementation path

You have three realistic options:

Option A: Adobe/native updates (if available on your version)

Check whether your Magento or Adobe Commerce version includes a maintained FedEx REST carrier. If yes, plan a upgrade-first path and regression-test rates against SOAP baselines.

Option B: Replace with a maintained REST extension

For most merchants we support, a dedicated Magento 2 FedEx OAuth shipping extension is faster and lower risk than patching core. Look for:

  • OAuth token caching (tokens expire; avoid requesting a new token on every rate request)
  • Configurable services (Ground, Home Delivery, Express) mapped to Magento methods
  • Logging with masked credentials
  • Hyvä and headless checkout compatibility if you are not on Luma

Option C: Custom module

Build a carrier model that implements Magento\Quote\Model\Quote\Address\RateRequest → FedEx REST JSON. Only choose this if you have unique rating logic (dry ice, multi-origin dropship) that off-the-shelf modules do not cover.

Step 4: Configure and parallel-test rates

Never flip production in one deploy. Run SOAP and REST in parallel on staging:

  1. Configure REST with sandbox credentials
  2. Build a basket matrix: light parcel, heavy parcel, residential vs commercial, Alaska/Hawaii if you ship there
  3. Compare REST quotes to your last known SOAP quotes (± a few cents is normal; large deltas mean wrong service mapping)

Example REST rate request structure (simplified):

{
  "accountNumber": { "value": "XXXXXX" },
  "requestedShipment": {
    "shipper": { "address": { "postalCode": "60601", "countryCode": "US" } },
    "recipient": { "address": { "postalCode": "90210", "countryCode": "US" } },
    "pickupType": "DROPOFF_AT_FEDEX_LOCATION",
    "rateRequestType": ["LIST", "ACCOUNT"],
    "requestedPackageLineItems": [{ "weight": { "units": "LB", "value": "5" } }]
  }
}
Enter fullscreen mode Exit fullscreen mode

Log full request/response pairs during testing. FedEx error payloads are JSON and much easier to debug than SOAP fault strings.

Step 5: Update integrations and go live

Once rates match:

  1. Disable the legacy FedEx carrier in admin (do not delete config yet)
  2. Enable the REST carrier with production credentials
  3. Re-test checkout end-to-end: logged-in, guest, multi-shipment quotes if applicable
  4. Update ERP/WMS mappings if they consumed SOAP tracking numbers differently
  5. Monitor var/log and New Relic/Datadog for 401/403 spikes (usually expired or uncached tokens)

Keep SOAP credentials for one sprint as rollback insurance, then revoke them in the FedEx portal.

Common migration pitfalls

Packing weight vs dimensional weight. REST is stricter about box dimensions. If you only pass weight, expect occasional mismatches vs the old integration.

Residential surcharges. Ensure the REST request sets residential flags from the quote address; Magento's RateRequest exposes this via getDestType().

Multi-origin and dropship. Vendor modules that call FedEx per origin need each origin's ship-from address in the REST payload. If you run marketplace logic, Towering Media can help audit multi-vendor shipping integrations alongside your FedEx REST API migration.

Cached config. After deployment, run bin/magento cache:flush and verify config.php does not lock old carrier settings in env.php overrides.

Deadline urgency

FedEx has been winding down SOAP support for new projects since the REST launch; existing SOAP consumers face increasing instability. If checkout shipping is business-critical, schedule migration this quarter—not after peak season when carrier APIs are least forgiving.

Summary checklist

  • [ ] Audit codebase and extensions for SOAP FedEx usage
  • [ ] Create FedEx Developer Portal REST + OAuth credentials (sandbox first)
  • [ ] Implement REST carrier (extension or custom) with token caching
  • [ ] Parallel-test rate matrix on staging
  • [ ] Cut over production; monitor errors for 72 hours
  • [ ] Revoke legacy SOAP keys

About the author: Branden Thomas is cofounder of Towering Media, a Chicago Magento and Adobe Commerce agency since 2008. Towering Media builds FedEx REST, UPS REST, and USPS OAuth shipping integrations for US and Canadian merchants.

Top comments (0)