FedEx SOAP to REST Migration

Overview

FedEx is transitioning from a SOAP-based API to a REST-based API. While the core functionality remains the same, REST introduces stricter validation rules, updated default values, and revised behavior that may impact rating and label generation.

This guide outlines both domestic and international differences to support migration from FedEx SOAP to REST via EasyPost.

Domestic and General Changes

Field-Level Differences

International-Specific Differences

Field-Level Differences

TAXIDNBR.CNPJCPF.INVALID

CARRIAGEVALUECURRENCY.CUSTOMSVALUECURRENCY.MISMATCH

International Battery Shipments (REST)

REST expands support for international battery shipments compared to SOAP. 

Behavior Differences

• SOAP: Supported international battery shipments only (single shipments).
• REST: Supports both international battery shipments and orders (MPS).

Orders (MPS) 

When creating an order that contains multiple shipments:

• Each shipment that contains batteries must include the appropriate options.hazmat value.
• Not all shipments in the order are required to contain batteries.
• Shipments without a hazmat value are treated as non-battery shipments.

When labels are generated:

• Shipments containing batteries display ELB on the label.
• Shipments without batteries do not display ELB. 

Required Configuration

For each shipment containing batteries:

{
  "order": {
    "service": "FEDEX_INTERNATIONAL_CONNECT_PLUS",

<REST-OF-ORDER-HERE>

"shipments": [
      {
        "parcel": {
          "length": 12.0,
          "width": 10.0,
          "height": 5.0,
          "weight": 10.0
        },
        "options": {
          "hazmat": "SECONDARY_PACKED"
        }
      },
      {
        "parcel": {
          "length": 12.0,
          "width": 10.0,
          "height": 5.0,
          "weight": 10.0
        },
        "options": {
          "hazmat": "PI966-II"
        }
      },
      {
        "parcel": {
          "length": 12.0,
          "width": 10.0,
          "height": 5.0,
          "weight": 10.0
        },
        "options": {
          "hazmat": "LITHIUM"
        }
      },
      {
        "parcel": {
          "length": 12.0,
          "width": 10.0,
          "height": 5.0,
          "weight": 10.0
        }
      }
    ]

Supported battery types include:

• SECONDARY_PACKED
• PI966-II
• LITHIUM

Limitations

• Only battery hazmat shipments are supported
• Non-battery dangerous goods are not supported in REST.
• Unsupported hazmat shipments may return no rates or serviceability error.

RATE.LOCATION.NOSERVICE

Behavioral Changes

These changes affect returned messaging or rate responses but do not change shipment eligibility.

Saturday Delivery

Behavior remains the same in SOAP and REST, but error messaging differs between rate and buy. 

Example

"options": {
  "saturday_delivery": true
}

If Saturday delivery is not valid for the origin/destination:

Rating Error

RATE.LOCATION.NOSERVICE

Buying Error

ORGORDEST.SPECIALSERVICES.NOTALLOWED

Saturday Delivery - FedEx Wallet Accounts (SmartPost)

For FedEx Wallet accounts, behavior has changed when Saturday Delivery is requested.

SOAP Behavior

When Saturday Delivery was requested, SMART_POST rates could still be returned. 

REST Behavior

SMART_POST rates are no longer returned when Saturday Delivery is requested. FedEx cannot guarantee Saturday delivery for SMART_POST services.

This change affects rate responses only. Shipment eligibility rules remain unchanged.

Windsor Framework (GB to NI) - AWB Changes

Previous SOAP behavior:

• Generated a physical Air Waybill (AWB)
• Generated a non-electronic Commercial Invoice

REST behavior:

• Submits a Digital Commercial Invoice via ETD
• No longer generates a physical AWB

Shipping labels now display an ETD indicator.

FAQs

Q: What does the error message “We are not able to retrieve the message for the warning or error” mean?

A: This message appears when buying labels in EasyPost test mode using FedEx.

In test mode, EasyPost sends buy requests to the FedEx sandbox servers rather than the production environment. While both environments return the same error codes, the sandbox does not include descriptive error messages.

For example:

• Production response:
  ORGORDEST.SPECIALSERVICES.NOTALLOWED: : This special service type is not allowed for the origin/destination pair. Please update and try again.:
• Test mode response:
  ORGORDEST.SPECIALSERVICES.NOTALLOWED: : We are not able to retrieve the message for the warning or error.

This is expected behavior in test mode and does not indicate a system issue.

Q: What happens if I send a full state name in the REST API? 

A: The request will be rejected. Use 2-letter state or province abbreviations. 

Q: Can I leave the phone number field empty?

A: No. In REST, the phone number is mandatory and must contain 10 digits for U.S. and Canadian addresses. 

Q: Can I still use extensions in phone numbers with FedEx? 

A: No. FedEx REST only supports 10-digit numbers. Extensions will be silently truncated and omitted from the label and request.

Q: Is it required to include both person_name and company_name?

A: No. Only one of the two is required, but whichever is used must be at least three characters long. 

Q: Why does my SmartPost shipment fail with the declared value set? 

A: SmartPost does not support declared value in REST. Remove this field from the request.

Q: Are all battery shipments rejected in REST? 

A: No. Non-hazmat batteries are supported. All other dangerous goods are rejected.

Q: Why does the currency need to be consistent? 

A: REST requires that all shipment-related currency fields (such as customs_value and carriage_value) use the same currency. 

Error: CARRIAGEVALUECURRENCY.CUSTOMSVALUECURRENCY.MISMATCH 

Q: What if I don’t know the location_id for a Hold at Location shipment?

A: Leave it blank. If the location_id is not accurate; FedEx may return a vague error (e.g., origin/destination not serviceable). Leaving the field blank is preferred — FedEx will then autopopulate it with the code. The label will match the format used from SOAP. 

Q: Do I need to change anything from Dropoff or Pickup type? 

A: This field is automatically mapped for you - continue to use the same values from before. If not specified, the default will change from REGULAR_PICKUP to USE_SCHEDULED_PICKUP (REST). The behavior is the same, but there may be different values in responses or logs. No updates to your integration are required.

Q: Are reference fields still truncated? 

A: Yes. Truncation still occurs as it did with SOAP, but the maximum character limits have changed slightly. This may impact what appears on the label, especially for important fields like CUSTOMER_REFERENCE. Be aware that labels for Ground vs Express may now show different character lengths. 

Additional Resources

EasyPost API Docs

Errors - API Docs