Rates

To successfully retrieve rates, you must provide key details. While the shipment object can include additional parameters, the following example highlights the minimum information required to generate accurate rates. The more specific your shipment details are, the more precise your rate results will be. For more information, please refer to the Rate Request page for more details and parameters.

Minimum Shipment Details (JSON Example)

 
{
   "shipment":{
      "to_location":{
         "first_name":"string", // or company
         "address1":"string",
         "city":"string",
         "state":"string", // for a US state use the two-digit state code
         "country":"string", // two-digit country code
         "postal_code":"string",
         "phone":"string"
      },      
      "from_location":{
         "company":"Test Test", // or first_name
         "address1":"string",
         "city":"string",
         "state":"string",
         "country":"string",
         "postal_code":"string",
         "phone":"string"
      },
      "parcels":[
         {
            "length":6.0, // inches
            "width":2.0, // inches
            "height":2.0, // inches
            "weight":36.0, // ounces
            "package_type":"string",
         }
      ]
   }
}

A request containing only this data will return rates for all enabled services your account qualifies for. For example, FedEx Ground and FedEx Home Delivery will not return for the same shipment since they are mutually exclusive depending on whether the destination (to_location) is residential or commercial.

If you wish to narrow the results, you can include one of the following parameters within the shipment object.

Service Filters

You can specify desired services using the include_services field, an array containing service IDs. The service IDs can be either an integer or a string that represents the ID of the service you want to retrieve rates for.

Service Filter Example (JSON)

 
{
	"include_services": [
		1172, // USPS Ground Advantage
		"686" // USPS Parcel Select
	]
}

Including this array in your request will limit the response to rates for USPS Ground Advantage and USPS Parcel Select only.

Carrier Filters

To include services from specific carriers only, use the include_carriers field:

Carrier Filter Example (JSON)

 
{
  "include_carriers": [
    "usps",
    "fed_ex",
    "dhl_ecommerce"
  ]
}

To exclude services from specific carriers, use the exclude_carriers field:

Exclude Carrier Example (JSON)

 
{
  "exclude_carriers": [
    "ups",
    "dhl_express"
  ]
}

If you omit filtering parameters, all available services will be available for the given shipment, as no specific services or carriers are excluded.

Warnings

If there are any issues retrieving rates, warnings or error messages from the carrier's API will be relayed back and stored in the warnings array of the response body. This allows for a successful response even if one carrier encounters an issue while others return rates successfully.

Warning Example (JSON)

 
{
  "warnings": [
    "FedEx returned error: Destination postal code missing or invalid"
  ]
}

How to Get FedEx OneRate Rates

To receive FedEx OneRate rates, you need to specify both the eligible package type and service based on the contract in the rating or shipment request. Follow these steps:

1. Make a GET /services Call

In the response, find the service object relevant to the FedEx service that qualifies for FedEx OneRate under the OneRate contract. The service is usually FedEx 2Day but may vary depending on the contract.

Example GET /services Response:

 
{
   "services": [
      ...
      {
         "service_id": 393, // <------
         "service": "FEDEX_2_DAY",
         "service_code": "fedex_2day",
         "carrier_code": "fed_ex",
         "category": "shipping",
         "package_types": [
            {
               "type": "fedex_pak", // <------
               "name": "FedEx Pak"
            }
         ],
         "sort_order": null
      }
      ...
   ]
}

In the service object, check the package_types array to find the package type specific to the FedEx OneRate contract. Note the services[i].package_types[i].type, as it will be needed later.

2. Use the service_id and package_type in the Rating Request

The shipments.parcels[i].package_type should be set to the package type agreed upon in the FedEx OneRate contract, such as fedex_pak

Example Rating Request:

 
{
   "shipment": {
      "to_location": {...},
      "return_location": {...},
      "from_location": {...},
      "parcels": [
         {
            "length": 2.0,
            "width": 2.0,
            "height": 2.0,
            "weight": 3.0,
            "package_type": "fedex_pak", // <------
            "parcel_items": [...]
         }
      ],
      "include_services": [393] // <------ fedex_2day
   }
}