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 |
| GET | /v1/diesel-prices/monthly-average | Monthly average of the EIA U.S. on-highway diesel price, month-to-date, and surcharge effective month. See Diesel monthly average |
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
}
}
}
Diesel monthly average
GET /v1/diesel-prices/monthly-average returns the calendar-month average of the EIA U.S. on-highway diesel price (series EMD_EPD2D_PTE_NUS_DPG, "Diesel (On-Highway) - All Types", USD per gallon), the index that monthly rail fuel surcharges are keyed to. It is available on every authenticated plan, including Free, for every month held. Standard quota and rate limits apply. It serves JSON only.
| Parameter | Description |
|---|---|
month | One month as YYYY-MM. Cannot be combined with start_month or end_month |
start_month | First month of a range as YYYY-MM |
end_month | Last month of a range as YYYY-MM. Defaults to the current month |
With no parameters you get the current month and the two before it. A range can span at most 120 months. Months are returned newest first. The current month is the month in New York time.
curl "https://api.oilpriceapi.com/v1/diesel-prices/monthly-average?month=2026-10" \
-H "Authorization: Token YOUR_API_KEY"
Each entry in data.months carries two figures that are never merged:
| Field | Meaning |
|---|---|
basis_month | The month the diesel prices were observed |
effective_month | basis_month plus two calendar months (October average, December surcharge) |
status | final (EIA has published the month), provisional (only the weekly mean exists) or unavailable |
provisional | true until EIA publishes its monthly value |
eia_monthly_average | EIA's own published monthly value (kind: "published"), served as published, or null before EIA publishes it. Includes first_seen_at, revised_at, previous_value and revision_count |
weekly_mean | OilPriceAPI's arithmetic mean of EIA's weekly prints dated in the month, rounded half up to 3 decimals (kind: "calculated"). Lists the weeks used, weeks_observed, weeks_in_month, complete, month_to_date, missing_weeks, warning and matches_eia_monthly |
For the open month, eia_monthly_average is null and weekly_mean is the month-to-date mean with month_to_date: true. If a weekly print EIA has already published is not held, weekly_mean.value is null and warning is weekly_prints_missing; nothing is interpolated. matches_eia_monthly is null until the month has both a complete set of weekly prints and EIA's value.
first_seen_at is when OilPriceAPI first read the value from EIA. EIA's API carries no release timestamp. When EIA revises a value, the response shows the new value with revised_at and previous_value.
The response also carries:
series: the EIA series id, name, units and EIA's own pages for it.surcharge_lag: the basis-month-plus-2 rule, the railroad programs whose public pages state it (Union Pacific, Norfolk Southern and CN, as read on 2026-11-13), CPKC as an exception that uses half-month periods, and BNSF and CSX as not verified. The applicable tariff or contract governs.coverage:earliest_month,latest_published_monthandlatest_weekly_period.freshness:last_successful_refresh_atandstale, which istruewhen EIA has not been read successfully in the last 36 hours. Stored values are still served whilestaleistrue.
Refusals return {"status": "fail", "data": {"error": "...", "code": "..."}}:
| Status | code | When |
|---|---|---|
400 | INVALID_MONTH | A month value that is not exactly YYYY-MM, including an empty or space-padded value |
400 | INVALID_MONTH_PARAMETERS | month sent together with start_month or end_month |
400 | INVALID_MONTH_RANGE | start_month is after end_month |
400 | MONTH_RANGE_TOO_LARGE | More than 120 months |
400 | MONTH_IN_FUTURE | A month that has not started; the body includes current_month |
400 | INVALID_FORMAT | Any format other than json |
404 | MONTH_BEFORE_COVERAGE | A month before the first one held; the body includes coverage |
404 | NO_DATA | No EIA on-highway diesel data is held yet |
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 | Free-tier daily quota exhausted (PAYMENT_REQUIRED), or a paid plan's monthly quota exhausted (MONTHLY_QUOTA_EXCEEDED) | Check reset.date or plan; do not retry immediately |
429 | Per-minute rate limit exceeded | Back off and retry after the 60-second window resets |
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.