Fuel Surcharge API
LTL fuel surcharge estimator for the 6 largest US LTL carriers. Uses each carrier’s published surcharge schedule at the current DOE on-highway diesel baseline, scales linearly when a different diesel price is supplied. JSON in, JSON out. CORS open. Free for 60 requests per hour without a key.
30-second start
POST your inputs. Get back the answer in JSON. No signup. No key required for the first 60 calls per hour per IP.
curl
curl -X POST https://www.wearewarp.com/api/v1/tools/fuel-surcharge \
-H "Content-Type: application/json" \
-d '{"base_rate":1000,"carrier":"old_dominion","diesel_price":5.50}'Or use GET with query params for one-liners:
curl GET
curl "https://www.wearewarp.com/api/v1/tools/fuel-surcharge?base_rate=1000&carrier=old_dominion&diesel_price=5.5"
Request
POST /api/v1/tools/fuel-surcharge
Omit diesel_price to use the cached DOE baseline:
curl
curl -X POST https://www.wearewarp.com/api/v1/tools/fuel-surcharge \
-H "Content-Type: application/json" \
-d '{"base_rate":1000,"carrier":"xpo"}'Response
Every response has a data envelope (the computed result) and a meta envelope (rate limits, docs, upgrade path, attribution).
200 OK
{
"data": {
"base_rate_usd": 1000,
"carrier": {
"slug": "old_dominion",
"name": "Old Dominion",
"published_surcharge_pct": 44.32,
"source": "live"
},
"diesel_price_used": 5.5,
"doe_diesel_baseline": 5.375,
"doe_data_updated_at": "2026-03-29T18:00:00Z",
"effective_surcharge_pct": 45.35,
"surcharge_amount_usd": 453.53,
"total_with_surcharge_usd": 1453.53
},
"meta": {
"request_id": "req_lzgk2zo_a1b2c3d4",
"tier": "anon",
"rate_limit": { "limit": 60, "remaining": 59, "reset_at": "2026-05-15T19:00:00.000Z" },
"docs": "https://www.wearewarp.com/developers/tools-api/fuel-surcharge",
"attribution": "Powered by Warp — https://www.wearewarp.com"
}
}Code samples
JavaScript (fetch)
const res = await fetch('https://www.wearewarp.com/api/v1/tools/fuel-surcharge', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({"base_rate":1000,"carrier":"old_dominion","diesel_price":5.50}),
});
const { data, meta } = await res.json();
console.log(data.base_rate);Python (requests)
import requests
res = requests.post(
"https://www.wearewarp.com/api/v1/tools/fuel-surcharge",
json={"base_rate":1000,"carrier":"old_dominion","diesel_price":5.50},
)
data = res.json()["data"]
print(data["base_rate"])curl with sandbox key
curl -X POST https://www.wearewarp.com/api/v1/tools/fuel-surcharge \
-H "Content-Type: application/json" \
-H "Authorization: Bearer wak_test_YOUR_KEY" \
-d '{"base_rate":1000,"carrier":"old_dominion","diesel_price":5.50}'Rate limits and tiers
No tier blocks access. Hit the limit and the response includes an upgradeURL with the next tier's signup flow.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. The meta.rate_limit object mirrors the same values in JSON.
Rate-limited response:
429 Too Many Requests
{
"error": "Anonymous rate limit reached (60/hr). Get a free sandbox key for 1000/hr at https://www.wearewarp.com/agents/account.",
"code": "RATE_LIMITED",
"meta": { "tier": "anon", "rate_limit": { "limit": 60, "remaining": 0 }, "upgrade": "..." }
}Errors
Bad input example:
400 Bad Request
{
"error": "Unknown carrier \"yrc\". Valid: fedex_freight, old_dominion, xpo, estes, saia, abf.",
"code": "BAD_INPUT",
"meta": { "request_id": "req_...", "docs": "https://www.wearewarp.com/developers/tools-api/fuel-surcharge" }
}Attribution
The free tier carries an attribution request: link back to wearewarp.com from any surface that displays results from this API. A “Powered by Warp” link in your footer is enough. Live keys remove the attribution request.
Every API response includes meta.attribution so you can render the link programmatically.
How the surcharge is calculated
- Carrier lookup. Each slug maps to the carrier’s published surcharge percentage at the current DOE on-highway diesel baseline. Sources: live (web-scraped weekly) or seed (carrier tariff snapshot).
- Diesel adjustment. diesel_price ÷ doe_diesel_baseline. If diesel_price is omitted, defaults to the cached DOE price and the adjustment is 1.0.
- Effective surcharge %. published_surcharge_pct × diesel_adjustment. Linear scaling — most LTL schedules are piecewise but step sizes are small enough that linear is within ~1% of actual on the published bands.
- Dollar impact. surcharge_amount = base_rate × effective_pct ÷ 100. total = base_rate + surcharge_amount.
DOE on-highway diesel is published weekly by EIA every Monday afternoon, and most carriers update their FSC schedules Wednesdays. The cached data behind this API refreshes weekly via scripts/fetch-doe-diesel.mjs. Warp ships all-inclusive — there is no separate fuel surcharge on a Warp invoice — but the calculator is here so shippers can benchmark.
Related
Get a free sandbox key
Sandbox keys take 30 seconds. No card. 1,000 calls per hour across every Warp tool API.