The Surcharge object is included in rate responses to provide clear visibility into the total shipping cost. Each surcharge applied by the carrier is categorized under a standardized structure (e.g., fuel, delivery_convenience, or handling), enabling consistent reporting across multiple carriers. This structure improves transparency, supports billing workflows, and enables detailed shipment cost analysis.
Surcharge objects are currently returned for the following carriers:
- FedEx
- UPS
- DHL eCommerce
- OnTrac v3 - categories coming soon
- Canada Post
- USPS
Refer to the carrier guides for details on surcharge behavior and supported services for each carrier.
Surcharge object
| Field | Type | Description |
type |
string | Carrier-specific surcharge code or description (e.g., FUEL_SURCHARGE, EXTENDED_AREA) |
category |
string | Standardized category enum assigned by EasyPost (see category definitions below) |
amount |
string | Fee amount as a string, matching the currency format in the rate or shipment. |
currency |
string | Currency code in ISO 4217 format (e.g., USD, CAD) |
Example
{
"rates": [
{
"service": "UPS_GROUND",
"rate": "15.00",
"currency": "USD",
"surcharges": [
{
"type": "FUEL_SURCHARGE",
"category": "FUEL",
"amount": "1.10",
"currency": "USD"
},
{
"type": "EXTENDED_AREA",
"category": "SERVICE_AREA_ADJUSTMENT",
"amount": "0.95",
"currency": "USD"
}
]
}
]
}Surcharge totals and validation
The surcharge object supports total cost validation for rates and shipments.
Use this structure to confirm accuracy in rating logic, detect billing discrepancies, or reconcile internal invoicing systems.
Surcharge categories
Each surcharge is mapped to a standardized category that helps normalize data across different carriers.
| Variable name | Descriptive title | Description | Carrier-specific surcharge examples |
ADDRESS_CORRECTION |
Address correction | Incorrect or incomplete address information |
ADDRESS_CORRECTION (FedEx), invalid_address_correction (OnTrak) |
CLEARANCE |
Clearance | Customs and regulatory processing fees |
ANCILLARY_FEE (FedEx) |
COMMODITY_TYPE |
Commodity type | Special handling for items like perishables or regulated goods |
ISC_TOBACCO (UPS), ISC_PLANTS (UPS) |
DANGEROUS_GOODS |
Dangerous goods | Charges for shipping hazardous goods |
DANGEROUS_GOODS (FedEx), dangerous_goods_charge` (DHL) |
DELIVERY_CONVENIENCE |
Convenience delivery options | Evening delivery, hold-at-location services |
HOLD_AT_LOCATION (FedEx), HOME_DELIVERY_APPOINTMENT (FedEx), HOLD_FOR_PICKUP (UPS) |
DEMAND |
Peak season/Demand | Temporary fees during high-volume shipping periods |
DEMAND_RESIDENTIAL_DELIVERY (FedEx), peak_season (DHL) |
EXCEPTION |
Exception handling | Services like rerouting or relabeling a shipment |
REROUTE (FedEx), RESCHEDULE (FedEx), relabel_charge (OnTrak) |
FUEL |
Fuel | Standard fuel surcharges |
FUEL (FedEx), fuel_surcharge (CA Post) |
HANDLING |
Handling | Oversized or irregular package charges |
HIGH_DENSITY (FedEx), OVER_DIMENSION (FedEx), OVERSIZE_PALLET (UPS), non-qualified_dim (DHL) |
HAZMAT |
Hazmat | Charges for hazardous material handling |
HAZMAT (UPS) |
INTERNATIONAL_HANDLING |
International handling | Processing fees for international shipments |
ORIGIN_CERTIFICATE (UPS), IMPORT_CONTROL_PRINT_LABEL (UPS) |
OTHER |
Other/Miscellaneous | Surcharges that do not fit other categories |
live_animal (USPS), DIRECT_TO_RETAIL (UPS) |
PAYMENT_TYPE |
Payment type | Charges related to billing methods like COD |
THIRD_PARTY_COSIGNEE (FedEx), SHIPMENT_COD (UPS) |
REBATE |
Rebate | Volume-based pricing adjustments |
volume_rebate_base (OnTrak) |
RETURNS |
Return surcharges | Return labels, pickup fees, and multiple attempts |
RETURN_LABEL (FedEx), RETURN_SERVICE_1ATTEMPT (UPS), return_extra_weight (OnTrak) |
SECURITY |
Security | Shipment security surcharges |
ENHANCED_SECURITY (FedEx), SECURITY_SURCHARGE (UPS) |
SERVICE_AREA_ADJUSTMENT |
Service area adjustment | Remote or difficult-to-access locations |
LIMITED_ACCESS_DELIVERY (FedEx), EXTENDED_AREA (UPS) |
SHIPMENT_VALUE |
Shipment value | Declared value and insurance-related charges |
INSURED_VALUE (FedEx), EXCESS_VALUE (FedEx) |
SIGNATURE_SERVICE |
Signature services | Signature service |
SIGNATURE_OPTION (FedEx), certified_adult_signature (UPS) |
SPECIAL_SERVICE |
Special services | Special services |
TARP, PRIORITY_ALERT (FedEx), LIFT_GATE_FOR_PICKUP (UPS) |
VALUE_ADD |
Value-add service | Value-add service |
value_added_service (DHL) |
WEEKEND |
Weekend | Weekend |
SATURDAY_PICKUP (FedEx) SATURDAY_INTERNATIONAL_PROCESSING_FEE (UPS), weekend_per_piece (OnTrak) |
UNKNOWN |
Unknown | Unknown |
Best Practices
- Use the
categoryfield for filtering and reporting to ensure consistency across carriers. - Expect surcharges under
DEMAND,FUEL, andSERVICE_AREA_ADJUSTMENTto change seasonally or frequently–avoiding hardcoding these values. - Monitor for surcharges with the
UNKNOWNcategory; these indicate a new or unmapped carrier fee and are flagged for internal updates.
FAQs
Q: Is the total cost affected by the surcharge object?
A: No. The surcharge object breaks down the components of the total cost, but does not alter the rate.
Q: Are surcharge objects returned after label purchase?
A: Yes. The shipment object includes the same surcharge breakdown found in the original rate.
Q: How are newly introduced surcharges handled?
A: Unrecognized surcharge types are labeled with the UNKNOWN category until mapped to an existing or new category.
Q: Is it normal for surcharges to come back as $0.00?
A: Yes. Each carrier handles surcharges differently and sometimes returns $0.00 to a surcharge string if it is not applicable.
Q: Can surcharges vary between carriers for the same service?
A: Yes. Each carrier uses its own surcharge structure; the standardized categories help normalize these differences.
Q: How can I enable surcharge visibility for my shipments?
A: Contact support@easypost.com to get access to the surcharge feature flag.