FedEx is transitioning from a SOAP-based API to a REST-based API. This guide outlines key differences between the two protocols to support customers migrating from FedEx SOAP to REST via EasyPost. REST introduces stricter data validation, new default values, and updated field behavior that may affect shipment creation.
Field-Level Differences
| Field | SOAP Behavior | REST Behavior | Error Example(s) |
| Person Name | No minimum length | Must be at least 3 characters |
PERSONNAME.TOO.SHORT
|
| Company Name | No minimum length | Must be at least 3 characters |
COMPANYNAME.TOO.SHORT
|
| Name Requirement | None |
Either person_name or company_name
required
|
|
| State/Province Code | Accepts full names and 2-letter abbreviations | Requires 2-letter code only |
STATEORPROVINCENAME.TOO.LONG
|
| Phone Number | Can be empty or any length | Must be 10 digits (U.S. and Canada) |
PHONENUMBER.TOO.SHORT, PHONENUMBER.EMPTY
|
| Dropoff/Pickup Type |
Default is REGULAR_PICKUP
|
Default is USE_SCHEDULED_PICKUP (same functionality,
different value
|
|
| Reference Fields | No length restrictions |
Length limits by field name:
|
VALUE.TOO.LONG
|
| Currency | Can vary across shipment elements | Must be uniform across shipment and customs values |
|
| Declared Value (SmartPost) | Allowed | Not supported |
|
| Hold at Location |
location_id is optional
|
Location_id is required; pulled from
address.carrier_facility if present
|
|
| Batteries/Hazmat | All are marked as dangerous goods | Only non-hazmat batteries supported; all other dangerous goods are rejected | Shipment may fail, or return rate differences |
| Saturday Delivery (when not applicable) |
Error message:
Buying:
|
New error message: Rating:
|
Buying a shipment that would be delivered on a different day other than Saturday fails.
Example,
Fails in both SOAP and REST. The error message has changed (and is now different for rating / buying), but behavior remains the same. |
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.