UPS Just Deprecated Their XML API: Magento 2 Migration Guide

If your Magento store still pulls UPS rates through the legacy XML API, treat that integration as expired—not "working fine for now."

UPS has been winding down XML access in favor of REST APIs with OAuth 2.0. Magento's built-in UPS carrier was built for the old model: Access Key, User ID, Password, and XML payloads over HTTP. That stack is increasingly unreliable, and when it fails, checkout shows no UPS options with little useful error detail in admin.

At Towering Media, we have migrated US and Canadian merchants off UPS XML alongside FedEx SOAP and USPS Web Tools migrations. This guide covers what changed, how to audit your store, and the production path we use for Magento 2 and Adobe Commerce.

What UPS changed (and why XML is a liability)

The legacy UPS integration most Magento stores know is the XML Rating and Shipping API accessed with static credentials. UPS now expects new integrations on the UPS Developer Portal using:

• REST endpoints (Rating, Shipping, Tracking as separate APIs)
• OAuth 2.0 client credentials (short-lived access tokens)
• JSON request and response bodies
• Separate sandbox and production credentials

This is not a URL swap. Authentication, error handling, and payload structure all differ from XML.

SOAP/XML failures tend to arrive without warning:

• UPS methods disappear from checkout while other carriers work
• Rate requests return empty with no admin log entry
• Label or tracking jobs fail during peak season when legacy throttling kicks in

If you already migrated FedEx or USPS to REST, UPS is the remaining legacy leg—delaying it leaves a single point of failure.

Step 1: Inventory every UPS touchpoint

Before changing credentials, map where UPS is used:

1. Stores → Configuration → Sales → Delivery Methods → UPS — core carrier settings
2. Custom modules — search for Ups, ups, AccessLicenseNumber, RatingService
3. Marketplace and dropship extensions — vendor-origin rating often wraps the legacy UPS model per warehouse
4. ERP, WMS, and label crons — batch jobs may hardcode XML endpoints

From your Magento root:

grep -ri "ups" app/code vendor/your-namespace --include="*.php" --include="*.xml" | grep -i "rate\|ship\|carrier"

Document which environments use production vs test credentials. REST OAuth keys are not interchangeable with XML Access Keys.

Step 2: Create UPS REST credentials

In the UPS Developer Portal:

1. Create an application (or use your organization's existing app)
2. Enable Rating API and Shipping API if you print labels from Magento
3. Note your Client ID, Client Secret, and UPS account number
4. Start in the Customer Integration Environment (CIE) sandbox; production credentials are separate

OAuth uses the client credentials grant:

POST https://wwwcie.ups.com/security/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials

Production uses https://onlinetools.ups.com/security/v1/oauth/token. The response includes a short-lived access_token you must cache—not request fresh on every rate call.

Step 3: Choose your Magento implementation path

Option A: Core or Adobe Commerce updates

Check whether your Magento version ships a maintained UPS REST carrier. If yes, plan an upgrade-first path and regression-test rates against your last known XML baselines.

Option B: Replace with a maintained REST extension

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

• OAuth token caching with automatic refresh before expiry
• Configurable services (Ground, 3 Day Select, Next Day Air) mapped to Magento methods
• Residential and commercial address handling from quote data
• Structured logging with masked credentials
• Hyvä and headless checkout compatibility

Option C: Custom module

Build a carrier model that maps RateRequest to UPS REST JSON only for unique multi-origin or packaging logic. Marketplace stores should audit multi-vendor FedEx, USPS, and UPS dropship integrations alongside UPS migration.

Step 4: Parallel-test rates on staging

Never flip production in one deploy. Run XML (if still working) and REST side by side on staging:

1. Configure REST with CIE sandbox credentials
2. Build a basket matrix: light parcel, heavy parcel, residential vs commercial, Alaska/Hawaii if applicable
3. Compare REST quotes to last known XML quotes (small deltas are normal; large gaps mean wrong service mapping)

Example REST rating request structure (simplified):

{
  "RateRequest": {
    "Shipment": {
      "Shipper": { "Address": { "PostalCode": "60601", "CountryCode": "US" } },
      "ShipTo": { "Address": { "PostalCode": "90210", "CountryCode": "US" } },
      "ShipFrom": { "Address": { "PostalCode": "60601", "CountryCode": "US" } },
      "Package": { "PackagingType": { "Code": "02" }, "PackageWeight": { "Weight": "5", "UnitOfMeasurement": { "Code": "LBS" } } }
    }
  }
}

Log full request/response pairs during testing. UPS REST error payloads are JSON and far easier to debug than XML fault strings.

Step 5: Cut over and monitor

Once rates match:

1. Disable the legacy UPS carrier in admin (keep config for rollback one sprint)
2. Enable the REST carrier with production OAuth credentials
3. Re-test checkout: guest, logged-in, multi-shipment quotes if applicable
4. Update ERP/WMS mappings if tracking number formats changed
5. Monitor logs for 401/403 spikes—usually expired or uncached tokens

Run bin/magento cache:flush after deployment and verify env.php does not lock old carrier settings.

Common migration pitfalls

Negotiated vs published rates. REST requires explicit rate request types. If you only request list rates, account-negotiated pricing may not appear.

Dimensional weight. REST is stricter about package dimensions. Weight-only requests can produce mismatches vs the old XML integration.

Multi-origin dropship. Vendor modules that call UPS per origin need each ship-from address in the REST payload. One global origin config is not enough for marketplace stores.

Token thrashing. Requesting a new OAuth token on every rate call adds latency and can trigger UPS rate limits.

Why this is urgent

FedEx SOAP and USPS Web Tools migrations are already production reality for most serious Magento stores. UPS XML is the remaining legacy carrier for many US merchants. Peak season is the worst time to discover your rating integration no longer responds.

If checkout shipping is business-critical, schedule UPS REST migration this quarter—not after your next FedEx/USPS fire drill.

Summary checklist

• [ ] Audit codebase and extensions for legacy UPS XML usage
• [ ] Create UPS Developer Portal REST + OAuth credentials (CIE 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 XML Access Keys in the UPS portal

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