FedEx XML to REST API Migration Guide

Overview

FedEx is sunsetting its legacy XML API on May 1, 2026. All accounts must migrate to the FedEx REST API via AfterShip before April 30, 2026, to avoid service disruption. This guide covers everything you need to know.

Part 1: How to Update Your FedEx Account

1.1. UI based flow

Follow these steps in AfterShip Shipping to migrate your existing FedEx account from XML to REST API integration.

Identify accounts that need updating: Go to the AfterShip Shipping Carrier accounts page. Your FedEx account will display the banner: "Please update the account before Apr 30, 2026". This means your account needs updating.

Accept the updated EULA: Click "Update", scroll through the FedEx End-User License Agreement, and tick the acceptance checkbox saying **“I have read and accept the FedEx End-User License Agreement.” **

Validate your account details: Click “Next” and re-enter your FedEx account number and shipping address. The address must exactly match your FedEx profile, otherwise the system will trigger an "Account address mismatch" error.

Complete multi-factor authentication (MFA): Click “Next” and select how you wish to complete the MFA. You can choose to receive a PIN via email, SMS, or phone call, or verify using an invoice.

Verify the PIN/invoice details: Enter the PIN or invoice details, based on your selection and click "Verify".
Configure additional settings: You can also set your preferred currency, enable ETD, and upload your letterhead and image files at any time from the carrier account settings pages.

Click Submit.

Some FedEx accounts are exempt from the MFA step and will be migrated automatically after address validation. Contact your FedEx account manager if you are unsure which applies to you.

1.2. API-based flow

Update your shipper account with an invoice from the past 90 days for MFA validation. If you want to enable FedEx ETD, also include commercial_invoice_letterhead and commercial_invoice_signature

To enable ETD, include both commercial_invoice_letterhead and commercial_invoice_signature. Otherwise, you do not need to include them. Even if you have already uploaded them (or asked AfterShip to upload them for you) in the legacy system, you must upload them again for the migration.
commercial_invoice_letterhead must be in PNG format and no larger than 700 pixels wide by 50 pixels tall. The commercial_invoice_signature must be in PNG format and no larger than 240 pixels wide by 25 pixels tall.
An invoice is required for the MFA validation update action.
credentials, address, and preferred_currency are optional but recommended. If you do not include them in the request payload, the system will use your existing account number and address for validation. However, there is a risk that they may not match your latest data in the FedEx system. Therefore, it is recommended to always include them for accurate validation.

POST https://api.aftership.com/postmen/v3/couriers/fedex/shipper-accounts/{id}/update

Request example:

{
    "invoice": {
        "number": "234562278",
        "currency": "USD",
        "date": "2026-02-24",
        "amount": 234
    },
    "credentials": {
        "account_number": "11111111"
    },
    "address": {
        "country": "USA",
        "contact_name": "Test name",
        "phone": "14158523888",
        "fax": null,
        "email": "test@aftership.com",
        "company_name": null,
        "company_url": null,
        "street1": "15 W 18TH ST FL 7",
        "street2": null,
        "street3": null,
        "city": "NEW YORK",
        "state": "NY",
        "postal_code": "100114624",
        "type": "residential",
        "tax_id": null
    },
    "settings": {
        "preferred_currency":"USD",
        "commercial_invoice_letterhead": "**",
        "commercial_invoice_signature": "**"
    }
}

Part 2: FedEx Service Changes

2.1. Newly Added Services

The following services are new in the REST API and were not available in the legacy XML integration:

service_type	service_name	FedEx Code	Ships From
`fedex_economy`	FedEx Economy	FEDEX_ECONOMY	CHL, ZAF
`fedex_economy`	FedEx® Economy	FEDEX_ECONOMY_SELECT	GBR
`fedex_first`	FedEx® First	FEDEX_FIRST	CHL, ZAF, EU region
`fedex_priority`	FedEx® Priority	FEDEX_PRIORITY	CHL, ZAF, MYS, THA, EU region
`fedex_priority_express`	FedEx® Priority Express	FEDEX_PRIORITY_EXPRESS	CHL, ZAF, THA, EU region

2.2. Discontinued Services

The following legacy services will no longer be supported after migration to the REST API. You can continue using them until you update your FedEx account, but once the update is complete, you must switch to the replacement services listed in this guide, otherwise your label generation will fail.

Service Type	Replacement / Note
`fedex_international_ground`	Use `fedex_ground`.
`fedex_international_priority_eod`	Use `fedex_international_priority`.
`fedex_next_day_afternoon`	Use the new UK domestic portfolio, as applicable: `fedex_economy`, `fedex_priority`, `fedex_priority_express`, or `fedex_first`.
`fedex_next_day_end_of_day`	Use the new UK domestic portfolio, as applicable: `fedex_economy`, `fedex_priority`, `fedex_priority_express`, or `fedex_first`.
`fedex_next_day_early_morning`	Use the new UK domestic portfolio, as applicable: `fedex_economy`, `fedex_priority`, `fedex_priority_express`, or `fedex_first`.
`fedex_next_day_mid_morning`	Use the new UK domestic portfolio, as applicable: `fedex_economy`, `fedex_priority`, `fedex_priority_express`, or `fedex_first`.
`fedex_distance_deferred`	Not supported in the FedEx REST API.
`fedex_priority_overnight_extra_hours`	Not supported in the FedEx REST API.
`fedex_standard_overnight_extra_hours`	Not supported in the FedEx REST API.
`fedex_first_overnight_extra_hours`	Not supported in the FedEx REST API.
`fedex_europe_first_international_priority`	Not supported in the FedEx REST API.
`fedex_regional_economy_freight`	Not supported by AfterShip.
`fedex_first_freight`	Not supported by AfterShip.
`fedex_freight_economy`	Not supported by AfterShip.
`fedex_freight_priority`	Not supported by AfterShip.
`fedex_priority_freight`	Not supported by AfterShip.

2.3. Service Name Changes

The following services remain fully supported, but their display names have changed. Update any name-based logic in your workflows accordingly.

service_type	Legacy Name	New Name
`fedex_regional_economy`	FedEx Regional Economy®	FedEx® Regional Economy
`fedex_international_connect_plus`	FedEx International Connect Plus	FedEx® International Connect Plus
`fedex_standard_overnight_one_rate`	FedEx Standard Overnight® One Rate	FedEx One Rate® - FedEx Standard Overnight®
`fedex_2_day_one_rate`	FedEx 2Day® One Rate	FedEx One Rate® - FedEx 2Day®
`fedex_2_day_am_one_rate`	FedEx 2Day® A.M. One Rate	FedEx One Rate® - FedEx 2Day® A.M.
`fedex_express_saver_one_rate`	FedEx Express Saver® One Rate	FedEx One Rate® - FedEx Express Saver®
`fedex_first_overnight_one_rate`	FedEx First Overnight® One Rate	FedEx One Rate® - FedEx First Overnight®
`fedex_priority_overnight_one_rate`	FedEx Priority Overnight® One Rate	FedEx One Rate® - FedEx Priority Overnight®

2.4. User-Facing Behavior Changes

The following changes affect how the API handles data and labels. Review each item and update your parsing, validation, or label-generation logic where applicable.

Change	Before	After	User Impact
ETD enablement	ETD enablement is set at the API request level, with `service_options = "paperless_invoice"`.	ETD enablement is set at the FedEx account level.	To enable ETD, set up your FedEx account with “Enable Electronic Trade Documents (ETD)” and upload your letterhead and signature files. Remove "paperless_invoice" from your API request.
Commercial invoice format	If ETD is not enabled, the generated commercial invoice uses the AfterShip format.	The commercial invoice always uses the FedEx format.	The commercial invoice will always be in the FedEx format, regardless of whether ETD is enabled.
Rate response `detail_charge.type` naming for surcharges	`detail_charge.type` was derived from `surcharges.description`, e.g., `additional_handling_surcharge_-_weight`.	`detail_charge.type` is now derived from `surcharges.type`, e.g., `additional_handling`.	If you parse or match `detail_charge.type`, update your mapping logic accordingly.
Phone number normalization and max length	No strict FedEx-specific length handling was applied.	Non-digit characters are stripped, and the phone number must be at most 15 digits. Requests exceeding 15 digits will fail.	Most users are unaffected. However, some labels may now fail if the normalized phone number exceeds 15 digits.
Weight precision normalization	Commodity weight kept 4 decimal places, and package or total weight kept 3 decimal places.	Commodity, package, and total weight are all normalized to 2 decimal places.	Displayed or submitted weights may change slightly due to rounding. This also reduces FedEx weight mismatch errors.
City length validation	No FedEx-specific minimum or maximum city length check was applied.	`city` must be between 3 and 35 characters.	Labels will now fail if the `city` is shorter than 3 or longer than 35 characters.
Item description truncation	`item description` was not truncated before being sent to FedEx.	`item description` is truncated to 50 characters.	Content beyond 50 characters is no longer sent to FedEx and will not appear on the label.
USA domestic return labels paper size	For USA domestic return shipments, the system cropped the FedEx output and returned a standard 4×6 label if paper_size was set to `4x6` or left empty.	For USA domestic return shipments, the system now forces `LabelStockType = PAPER_4x6`, ignores the requested `paper_size`, and returns the original uncropped label from FedEx.	The label file size will always be `A4` for USA domestic return labels.
`paper_size = 4x6.75 removal`	Users could pass `paper_size = 4x6.75`, and the request was effectively treated as 4x6.	Users must now pass `paper_size = 4x6` instead.	Any workflow still sending `4x6.75` must be updated before migration.

2.5. API-specific account flow

If you use the API to manage your FedEx account with AfterShip, please note the following changes.

Change	Before	After	User Impact
Create FedEx account	API endpoint: `https://api.aftership.com/postmen/v3/shipper-accounts2` . Request payload requires slug, account_number, and address.	API endpoint: `https://api.aftership.com/postmen/v3/couriers/fedex/shipper-accounts2`. Request payload requires slug, account_number, address, and invoice.	Update the API endpoint and payload to include invoice for validation purposes. See the example below for the full payload.

{
    "slug": "fedex",
    "invoice": {
        "number": "234562278",
        "currency": "USD",
        "date": "2026-02-24",
        "amount": 234
    },
    "credentials": {
        "account_number": "11111111"
    },
    "address": {
        "country": "USA",
        "contact_name": "Test name",
        "phone": "14158523888",
        "fax": null,
        "email": "test@aftership.com",
        "company_name": null,
        "company_url": null,
        "street1": "15 W 18TH ST FL 7",
        "street2": null,
        "street3": null,
        "city": "NEW YORK",
        "state": "NY",
        "postal_code": "100114624",
        "type": "residential",
        "tax_id": null
    },
    "settings": {
        "preferred_currency": "USD",
        "commercial_invoice_letterhead": "xxxx",
        "commercial_invoice_signature": "xxxx"
    }
}

Notes:

a. You can create both FedEx and FedEx Ground® Economy accounts using the same API endpoint: https://api.aftership.com/postmen/v3/shipper-accounts. Specify the slug as fedex or fedex-smartpost in the request payload.
b. You can still use the existing API endpoint https://api.aftership.com/postmen/v3/shipper-accounts/{id}/settings to update commercial_invoice_letterhead and commercial_invoice_signature after account creation.

2.6. Migration Checklist - FedEx Service Changes

If you need international shipping, upload your letterhead and signature to the AfterShip system after updating your FedEx account.

✅ If your workflow depends on service_name, review the renamed services above and update any name-based rules.

✅ If your workflow depends on legacy UK domestic services, migrate to the new UK domestic portfolio listed above.

✅ If your workflow depends on discontinued services, check whether a replacement mapping is available before migration.

✅ If your workflow parses FedEx rate or label responses, review the behavior changes table above and update any validation or field-matching logic.

✅ If you still send paper_size = 4x6.75, update your request to 4x6.

Part 3: FedEx Ground® Economy (formerly FedEx SmartPost) Changes

3.1. Service Name Changes

All FedEx SmartPost services have been rebranded to FedEx Ground® Economy. Their service_type values remain unchanged, but their display names have been revised.

service_type	Legacy Name (SmartPost)	New Name (Ground Economy)
`fedex-smartpost_parcel_select`	FedEx SmartPost parcel select	FedEx Ground® Economy
`fedex-smartpost_parcel_select_lightweight`	FedEx SmartPost parcel select lightweight	FedEx Ground® Economy (Under 1lb)
`fedex-smartpost_bound_printed_matter`	FedEx SmartPost® Bound Printed Matter	FedEx Ground® Economy Bound Printed Matter
`fedex-smartpost_media`	FedEx SmartPost® Media	FedEx Ground® Economy Media Mail

3.2. User-Facing Behavior Changes

The following FedEx Ground® Economy behavior changes may require review on the user side:

Change	Before	After	User Impact
Label and rate now return `transit_time` and `delivery_date`	`transit_time` and `delivery_date` were empty or not returned.	`transit_time` and `delivery_date` are now returned.	You will receive additional ETA information. This is additive and has no negative impact unless your response parser assumes these fields are absent.
Label `tracking_numbers` now returns only the FedEx tracking number	The label response returned both the FedEx tracking number and the USPS tracking number.	The label response now returns only the FedEx tracking number.	If you expect two tracking numbers or still use the USPS tracking number, you need to update your logic.
Return labels now support `qr_code`	Return labels did not support `qr_code`.	Return labels now trigger RMA generation and return a `qr_code` file.	For customers using the Shipping API, you can include `print_options.qr_code` for return shipments and retrieve the QR code file from the API response. For customers using the Returns platform, you can enable the QR code option to improve the shopper return experience.
USA domestic return labels paper size	For USA domestic return shipments, the system returned a cropped 4×6 label.	For USA domestic return shipments, the system now forces LabelStockType = PAPER_4x6, ignores the requested paper_size, and returns the original uncropped label from FedEx.	The label file size will always be A4 for USA domestic return labels.

3.3. Migration Checklist - FedEx Ground® Economy

✅ If your workflow depends on the FedEx Ground® Economy (previously FedEx SmartPost) service_name, review the renamed services above and update any name-based rules.

✅ If your workflow depends on the old SmartPost naming, update any customer-facing references to the new FedEx Ground® Economy naming.

✅ If your workflow parses SmartPost label or rate responses, review the behavior changes table above and update any field expectations related to ETA, tracking numbers, QR code files, and return label output.

Updated on: 07/04/2026