Fuel Surcharge API

Use these endpoints to retrieve carrier-published fuel surcharge percentages for LTL freight and parcel shipping. Responses preserve the carrier's effective_date, the OilPriceAPI retrieved_at timestamp, and the carrier schedule source URL so you can decide whether a rate is current enough for billing, quoting, or audit workflows.

Newly launched

The fuel-surcharge endpoints are newly launched. Coverage and response fields may expand - check the changelog for updates.

Plan required: available to all authenticated plans. Standard quota and rate limits apply.

Endpoints

Method	Endpoint	Description
GET	`/v1/fuel-surcharge`	Latest LTL surcharge for every covered carrier with data
GET	`/v1/fuel-surcharge/{carrier}/latest`	Latest LTL surcharge for one carrier
GET	`/v1/fuel-surcharge/{carrier}/history`	Historical LTL surcharge rows for one carrier
GET	`/v1/fuel-surcharge/parcel`	Latest parcel surcharges grouped by carrier and service level
GET	`/v1/fuel-surcharge/parcel/{carrier}/latest`	Latest parcel surcharge for one carrier, optionally one service level
GET	`/v1/fuel-surcharge/parcel/{carrier}/history`	Historical parcel surcharge rows for one carrier and service level

Authentication

Authorization: Token YOUR_API_KEY

Carrier Slugs

LTL

Covered LTL carriers:

odfl, saia, estes, xpo, abf, tforce, averitt, southeastern-freight

Reserved but not yet covered LTL slugs return 404 with the current covered list. Reserved slugs include fedex-freight and rl-carriers.

Parcel

Covered parcel carriers:

ups, fedex, dhl

Parcel responses are grouped by service_level. Service levels are carrier-specific and can change; call the carrier's latest endpoint without service_level to discover current values.

Common examples include ground, air, international_air_export, international_air_import, and international_ground.

Parameters

LTL History

GET /v1/fuel-surcharge/odfl/history?per_page=12&page=1

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Page number
`per_page`	integer	No	`100`	Rows per page, max `100`

Parcel Latest and History

GET /v1/fuel-surcharge/parcel/ups/latest?service_level=ground
GET /v1/fuel-surcharge/parcel/ups/history?service_level=ground&per_page=12

Parameter	Type	Required	Description
`service_level`	string	Latest: no. History: yes.	Parcel service level, for example `ground` or `international_air_export`
`page`	integer	No	History page number
`per_page`	integer	No	History rows per page, max `100`

Response Fields

Field	Type	Description
`carrier`	string	Public carrier slug
`carrier_name`	string	Carrier display name
`mode`	string	`ltl` or `parcel`
`service_level`	string	Parcel service level. Only present on parcel rate rows.
`surcharge_percent`	number	Fuel surcharge percentage
`effective_date`	date	Date the carrier says the surcharge applies
`doe_diesel_price`	number or null	DOE diesel benchmark used for LTL surcharge tables, when available
`diesel_band`	object or null	LTL diesel-price band with `min` and `max`, when the carrier publishes a banded schedule
`source`	string	Carrier schedule URL used for the stored row
`retrieved_at`	datetime	UTC timestamp when OilPriceAPI retrieved the carrier schedule

Examples

Latest LTL Surcharge

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/odfl/latest" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "status": "success",
  "data": {
    "carrier": "odfl",
    "carrier_name": "Old Dominion Freight Line",
    "mode": "ltl",
    "surcharge_percent": 38.32,
    "effective_date": "2026-07-14",
    "doe_diesel_price": 3.72,
    "diesel_band": {
      "min": 3.7,
      "max": 3.75
    },
    "source": "https://www.odfl.com/us/en/resources/fuel-surcharge.html",
    "retrieved_at": "2026-07-14T05:00:00Z"
  }
}

Latest Parcel Surcharges for a Carrier

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/latest" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "status": "success",
  "data": {
    "carrier": "ups",
    "carrier_name": "UPS",
    "mode": "parcel",
    "service_levels": [
      {
        "carrier": "ups",
        "carrier_name": "UPS",
        "mode": "parcel",
        "service_level": "ground",
        "surcharge_percent": 25.25,
        "effective_date": "2026-07-20",
        "doe_diesel_price": null,
        "diesel_band": null,
        "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
        "retrieved_at": "2026-07-17T12:00:00Z"
      }
    ]
  }
}

One Parcel Service Level

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/latest?service_level=ground" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "status": "success",
  "data": {
    "carrier": "ups",
    "carrier_name": "UPS",
    "mode": "parcel",
    "service_level": "ground",
    "surcharge_percent": 25.25,
    "effective_date": "2026-07-20",
    "doe_diesel_price": null,
    "diesel_band": null,
    "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
    "retrieved_at": "2026-07-17T12:00:00Z"
  }
}

Parcel History

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/history?service_level=ground&per_page=2" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "status": "success",
  "data": {
    "history": [
      {
        "carrier": "ups",
        "carrier_name": "UPS",
        "mode": "parcel",
        "service_level": "ground",
        "surcharge_percent": 25.25,
        "effective_date": "2026-07-20",
        "doe_diesel_price": null,
        "diesel_band": null,
        "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
        "retrieved_at": "2026-07-17T12:00:00Z"
      }
    ],
    "meta": {
      "page": 1,
      "per_page": 2,
      "total_count": 13,
      "total_pages": 7
    }
  }
}

Error Cases

Status	When	Recovery
`400`	Parcel history request omits `service_level`	Call latest without `service_level` to list available service levels, then retry history
`401`	Missing or invalid API key	Send `Authorization: Token YOUR_API_KEY`
`404`	Unknown carrier, reserved carrier, or covered carrier with no retrieved data yet	Use the covered carrier list returned in the error body
`402`	Monthly quota exhausted	Check the reset time or plan; do not retry immediately
`429`	Rolling rate limit exceeded	Back off and retry after the rolling window

MCP Tool

The OilPriceAPI MCP server v2.6.0 exposes these endpoints through opa_get_fuel_surcharge.

Example agent prompts:

What is the current UPS ground fuel surcharge?
Show me ODFL fuel surcharge history.
List parcel fuel surcharge service levels for FedEx.