Overview
FedEx is sunsetting its legacy XML API on Jul 31, 2026. All accounts must migrate to the FedEx REST API via AfterShip before Jul 31, 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 Jul 31, 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 numberandshipping 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_letterheadandcommercial_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_letterheadmust be in PNG format and no larger than 700 pixels wide by 50 pixels tall. Thecommercial_invoice_signaturemust 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, andpreferred_currencyare 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.
POSThttps://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": "[email protected]", "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-accounts . Request payload requires slug, account_number, and address. | API endpoint: https://api.aftership.com/postmen/v3/couriers/fedex/shipper-accounts . 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": "[email protected]", "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.