Magento 2 Fedex shipping method integration migration from SOAP to RESTful API before June 2026

By | October 7, 2025
0 Comment
Spread the love

Quick plan — migrate Magento 2 FedEx integration from SOAP → FedEx REST (deliverable you can run before June 2026)

Nice, doable. Below is a compact, runnable migration plan with the most-important facts, code snippets, tests and a practical milestone schedule you can execute now. I cite official FedEx docs and Magento/Adobe resources for the load-bearing points.

Essential facts you must know (sources)

  • FedEx has replaced legacy SOAP Web Services with REST APIs and recommends migrating. FedEx Developer Center

  • FedEx REST uses OAuth 2.0 bearer tokens (tokens expire ~60 minutes) — you must request and cache tokens, refresh when expired. FedEx Developer Center+1

  • Key REST endpoints you’ll need: Rates (Rate & Transit Times), Ship (label/shipments), Track, Address Validation. Use the Rates API for rate quotes. FedEx Developer Center+1

  • Adobe/Magento have had patches and community work for FedEx REST migration — check Adobe Experience League and Magento GitHub entries when updating the core FedEx carrier logic or applying a vendor patch. Experience League+1

High-level migration checklist (do these in order)

  1. Inventory current SOAP usage

    • List each SOAP operation your store calls (Rates, Ship/Label, Track, Address Validation, PostalCodeValidate, etc.).

    • Record inputs & outputs currently relied on (e.g., package dims, special service codes, billing party).

  2. Map SOAP operations → FedEx REST APIs

    • Rates → Rates & Transit Times API.

    • Shipment creation / labels → Ship API.

    • Tracking → Track API.

    • Address validation → Address Validation API.
      (Use FedEx docs for exact request/response fields.) FedEx Developer Center+1

  3. Obtain FedEx developer credentials

    • Create a FedEx developer project, subscribe the required APIs, get Client ID and Client Secret (and sandbox/production modes). FedEx Developer Center

  4. Implement OAuth token flow & caching

    • Request an OAuth token and store it (cache or Magento config cache). Refresh when expired (~60 minutes). Make token retrieval a small reusable service. FedEx Developer Center

  5. Build a REST adapter/service layer

    • Create a PHP service class per API (RatesService, ShipService, TrackService) that:

      • Assembles REST payloads (translate Magento internal data to FedEx REST schema).

      • Handles OAuth header injection and token refresh.

      • Normalizes FedEx responses to the shape Magento expects.

  6. Replace carrier logic / integrate into Magento shipping carrier

    • Option A: Patch/override existing Magento\FedEx carrier classes to use the new services.

    • Option B: Create a custom carrier module that implements the same config keys and admin UI (Carrier Title, account info) and drops into Magento shipping carriers. (Cleaner and safer for upgrades.)

    See Adobe’s patch notes / community patches before editing core. Experience League+1

  7. Label formats & account details

    • Confirm label formats (PDF/ZPL) the Ship API returns — adapt printing/label storage. Verify billing/third-party account behavior matches your current flows.

  8. Validation / stricter schema

    • FedEx REST imposes stricter validation; add more robust validation and fallback mapping for fields that SOAP tolerated. (e.g., service codes, dimensions, package types)

  9. Testing

    • Sandbox testing for: rates parity, label creation, tracking lookups, address validation, and error handling.

    • Compare sample shipments between old (SOAP) and new (REST) to confirm rate/label equivalence where possible.

  10. Monitoring & rollback

  • Add logging for all FedEx REST calls and responses (store request/response IDs for support).

  • Implement feature flag / config toggles to switch back to legacy (if you keep legacy SOAP for a short period) — but FedEx legacy may be retired, so prefer sandbox validation and then cutover.

Important implementation details & snippets

1) OAuth token request (PHP curl, adapt to Magento service)

// simple example — put this in a token service and cache token with expiry
$clientId = 'YOUR_CLIENT_ID';
$clientSecret = 'YOUR_CLIENT_SECRET';
$tokenUrl = 'https://apis.fedex.com/oauth/token';

$ch = curl_init($tokenUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$post = http_build_query(['grant_type' => 'client_credentials', 'client_id' => $clientId, 'client_secret' => $clientSecret]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// $data['access_token'] and $data['expires_in'] (~3600s)

Cache access_token and expires_in in Magento cache (or DB) and refresh when expired. (FedEx docs: token ~60 minutes.) FedEx Developer Center

2) Example Rates request (outline)

  • Endpoint (Rates): use Rates API base path in FedEx docs; pass Authorization: Bearer <token> header.

  • Translate Magento package/address/service inputs into FedEx REST JSON schema. Check docs for requestedShipment fields, service codes and packaging type. FedEx Developer Center

(Do not rely on exact field names here — copy from FedEx Rates API docs when coding.)

Integration tips & pitfalls

  • Token caching is mandatory — don’t request token per shipment. Cache and refresh only when needed. FedEx Developer Center

  • Strict validation: REST may reject inputs SOAP accepted — add pre-send sanitization and meaningful admin errors. FedEx Developer Center

  • Test rates for edge cases: surcharges, one-rate, volumetric weight, discounts. Some request/response semantics changed (StackOverflow & community reports confirm nuances). Stack Overflow

  • Magento version / patching: if you’re on Magento/Adobe Commerce 2.4.x, check Adobe’s patch history for FedEx migration before modifying core. Download plugin from here https://www.ecomplugins.com/magento2-fedex-shipping-carrier-with-rest-api

Minimal milestone schedule (practical, you can start immediately)

  • Week 0 — Inventory & setup FedEx dev project (client id/secret, sandbox).

  • Week 1 — Implement OAuth token service + caching. Add logging. (Basic ready)

  • Week 2 — Implement RatesService and smoke-test rates in sandbox. Validate parity with SOAP. FedEx Developer Center

  • Week 3 — Implement ShipService (label creation), confirm label formats.

  • Week 4 — Track + Address Validation + additional services.

  • Week 5 — End-to-end testing, QA and edge-case fixes.

  • Week 6 — Staged rollout / switch to production credentials and monitor.

This schedule is aggressive but realistic for a focused dev team. Adjust based on QA needs, custom logic, and number of shipping edge-cases you support.

Acceptance criteria (how you’ll know migration succeeded)

  1. Rates returned from FedEx REST for representative orders match (within expected delta) the previous SOAP results.

  2. Create/print labels successfully in production format used in operations.

  3. Tracking updates available via REST match current tracking flows.

  4. No increase in failed shipments/errors after 7 days in production; clear error logs for any REST rejects.

Useful links (start here)