Home → Blog

Billing disputes are expensive. In trucking and ocean logistics, a single mismatch between a carrier invoice and a shipper’s TMS record can spiral into days of email threads, escalations, cash tied up in suspense accounts, and eroding carrier relationships. Finance and ops teams are often reconciling across scattered sources: fuel indices from one feed, market rates from another, port congestion context from a third, carrier compliance from a fourth, and weather disruptions from yet another. The result is manual copy-paste work, brittle spreadsheets, and a reconciliation process that breaks each time a provider changes a schema.

This post shows how to automate settlement reconciliation using one unified data backbone: FreightPulse. By consolidating fuel prices (EIA), live US FTL freight quotes, IMF PortWatch congestion signals, FMCSA/FMC carrier lookups, and natural-disruption alerts into a single REST API with a consistent JSON schema, FreightPulse helps finance and logistics engineering teams reduce adjustments, prevent short-pay disputes, and close books faster. We will walk through concrete endpoints, complete JSON examples, and pragmatic patterns that developers can ship into production—without stitching together five different feeds or overpaying for AIS data just to check whether a port slowdown explains a line-haul variance.

If your remit spans finance, audit, and logistics operations—especially within 3PLs, freight forwarders, brokerage platforms, and enterprise supply chains—this is a practical, code-forward guide to building automated reconciliation pipelines that proactively flag mismatches and document why any difference exists before it becomes a dispute.

Introduction: The settlement reconciliation problem in logistics finance

Modern transportation finance has a data entropy problem. A typical carrier invoice line includes a line-haul charge, a fuel surcharge indexed to diesel prices, and potentially accessorials tied to weather, port congestion, or special handling. Meanwhile, the shipper’s TMS or WMS may store quoted rates at booking time, planned pickup dates, and contract vs spot indicators—often without the live context that justifies exceptions. The friction appears in three places:

The result is reactive dispute handling. Finance teams wait for carriers to defend charges; carriers wait for shippers to approve; days or weeks pass while both sides scramble to assemble evidence from different systems. The longer a settlement stays open, the higher the cost and the worse the relationship.

An automated reconciliation service eliminates the scramble. With FreightPulse, you can compute expected charges as soon as the shipment is delivered, attach authoritative data (fuel index, rate benchmark, disruption context, carrier verification) to the settlement record, and surface only true anomalies to a finance reviewer. That means fewer back-and-forths and faster, cleaner month-end close.

Why FreightPulse for reconciliation: consolidate evidence, cut dispute cycles

FreightPulse consolidates key financial evidence needed for settlement checks into a single, developer-friendly surface. Here are practical reasons it matters for your reconciliation stack:

The net effect: faster builds, fewer disputes, and higher-quality audits. Implementation details matter, too: because all endpoints share a standard response envelope, your error handling, retries, and circuit-breaker logic can be applied once and reused across modules for fuel, rates, congestion, carriers, and disruptions.

Quick Start: Base URL, first request, and response anatomy

FreightPulse is a REST API with a consistent response envelope. The base URL is:

https://freightpulsehq.com/api/v1

Let’s start by retrieving the current national diesel and gasoline prices (EIA), which is foundational for validating fuel surcharges in settlements.

Example request (no parameters required): 

curl "https://freightpulsehq.com/api/v1/fuel-prices"

Example response: 

{
"success": true,
"data": {
"timestamp": "2026-07-30T12:00:00Z",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 3.847,
"change_week": -0.023,
"change_percent": -0.6,
"regions": {
"east_coast": 3.912,
"midwest": 3.756,
"gulf_coast": 3.623,
"rocky_mountain": 3.891,
"west_coast": 4.456,
"california": 4.892
},
"historical": {
"30d_avg": 3.82,
"90d_avg": 3.75,
"yoy_change_percent": -8.2
}
},
"gasoline": {
"national_average": 3.156,
"historical": {
"30d_avg": 3.1,
"90d_avg": 3.05,
"yoy_change_percent": 1.1
}
}
}
}
}

Key fields to use in finance automation:

One envelope, predictable structure. This same pattern holds across endpoints, which simplifies your reconciliation microservice design.

Core Endpoints for automated reconciliation

1) Fuel prices: GET /fuel-prices

Purpose: Calculate and validate fuel surcharge lines for trucking invoices. Finance teams often receive a surcharge computed on top of line-haul using a weekly diesel index. Without a consistent source-of-truth, reviewers rely on screenshots or ad-hoc webpages. With FreightPulse, you can deterministically compute surcharges during settlement.

Endpoint:

GET /fuel-prices

Parameters: None.

Example request: 

curl "https://freightpulsehq.com/api/v1/fuel-prices"

Response (complete example shown earlier). Practical usage notes:

2) Live freight rates: GET /freight-rates

Purpose: Compare invoiced line-haul against a live market quote captured near booking or pickup. Whether you’re benchmarking for spot procurement or validating a contract lane that was repriced, a consistent rate quote provides objective evidence to approve or flag differences.

Endpoint:

GET /freight-rates

Key parameters (trucking mode):

Example request (US FTL): 

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

Example response: 

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
}
}

Field meanings and reconciliation tips:

Ocean/air note: For finance reconciliation involving ocean imports, using mode=ocean with origin_country + dest_zip lets you approximate prevailing rate pressure for exception handling. Even if settlement adheres strictly to contract tariffs, a reference quote can justify or challenge additional surcharges submitted during disruptions.

3) Port congestion: GET /port-congestion

Purpose: Document context for delay-related charges (detention, demurrage, chassis splits) with a standardized congestion signal. Finance needs objective, reproducible measures, not anecdotal claims. FreightPulse approximates congestion from IMF PortWatch AIS data as a 7-day average portcalls vs a 90-day baseline; data is lagged ~6–7 days and is not real-time vessel wait time.

Endpoint:

GET /port-congestion

Key parameters:

Example request: 

curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Example response: 

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
}
]
}
}

Finance interpretation:

4) Carrier verification: GET /carriers

Purpose: Validate carrier identity and status (FMCSA for trucking, FMC for ocean NVOCC/OTI) before paying. Catching a mis-keyed DOT number, inactive status, or safety rating concerns early can prevent fraud or compliance issues.

Endpoint:

GET /carriers

Key parameters:

Example request (trucking by DOT number): 

curl "https://freightpulsehq.com/api/v1/carriers?q=54283"

Example response: 

{
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}

How finance uses it:

5) Natural disruptions: GET /disruptions

Purpose: Establish force majeure context for surcharge exceptions or delivery variances. When a cyclone, earthquake, or severe weather hits, carriers may apply surcharges or miss service levels. Finance needs a reliable, filterable feed that can be tied to a shipment’s geography and timeline.

Endpoint:

GET /disruptions

Key parameters:

Example request: 

curl "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Example response: 

{
"success": true,
"data": {
"results": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
}
}

Finance application:

6) Time series for audit trails: GET /historical

Purpose: Build an audit-grade paper trail of the exact index values that drove your surcharge or exception decisions over time. Historical diesel prices and port congestion series make variance analysis and quarterly policy reviews straightforward.

Endpoint:

GET /historical

Key parameters:

Example request (diesel, 30 days): 

curl "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

Example response: 

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "30d",
"series": [
{
"date": "2026-07-27",
"value": 5.257
},
{
"date": "2026-08-03",
"value": 5.343
}
]
}
}

Usage guidance:

End-to-end reconciliation flow with practical code

Below is a high-level approach to computing expected settlement values and assembling an evidence pack your AP system can use to auto-approve or flag invoices. We will demonstrate with JavaScript and Python-like pseudo-implementations for clarity.

JavaScript example: compute surcharge and benchmark line-haul 

// Fetch fuel index and market rate, then compute an expected settlement
// Assumes you have a shipment object with origin_zip, destination_zip, pickup_date, and invoiced amounts

async function fetchJSON(url) {
const res = await fetch(url);
const body = await res.json();
if (!body.success) throw new Error(body.error || 'Request failed');
return body.data;
}

function computeFuelSurcharge(indexPrice, baseline, incrementPer10c, miles) {
// Example formula: surcharge_cents_per_mile = max(0, ((indexPrice - baseline) / 0.10) * incrementPer10c)
// Then multiply by miles
const steps = Math.max(0, (indexPrice - baseline) / 0.10);
const centsPerMile = steps * incrementPer10c;
return (centsPerMile / 100) * miles;
}

async function buildSettlementEvidence(shipment) {
const fuelData = await fetchJSON("https://freightpulsehq.com/api/v1/fuel-prices");
const diesel = fuelData.data.diesel.national_average;

const rateData = await fetchJSON(
`https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=${shipment.origin_zip}&destination_zip=${shipment.destination_zip}`
);

const expectedFuel = computeFuelSurcharge(
diesel,
shipment.contract_fuel_baseline, // e.g., 1.25 USD/gal
shipment.increment_per_10c, // e.g., 0.5 cents/mile per $0.10
shipment.planned_miles
);

const expectedLinehaul = rateData.price_usd;
const variance = (shipment.invoiced_linehaul - expectedLinehaul) / expectedLinehaul;

return {
diesel_index: diesel,
market_quote: rateData,
expected_fuel_surcharge: Number(expectedFuel.toFixed(2)),
linehaul_variance_pct: Number((variance * 100).toFixed(2))
};
}

This example shows how to compute an expected fuel surcharge and benchmark line-haul. In production, persist both the inputs (diesel index, baseline, increment) and results for audit. Applying the same pattern, pull relevant congestion or disruption context and add them to your evidence pack.

Python example: enrich an ocean settlement with congestion and disruptions 

import requests

def get_json(url):
r = requests.get(url, timeout=15)
data = r.json()
if not data.get("success"):
raise RuntimeError(data.get("error", "request failed"))
return data["data"]

def ocean_evidence(locode):
congestion = get_json(f"https://freightpulsehq.com/api/v1/port-congestion?port={locode}")
disruptions = get_json(f"https://freightpulsehq.com/api/v1/disruptions?port={locode}&severity=high")
return {
"port_context": congestion.get("results", []),
"active_disruptions": disruptions.get("results", [])
}

# Example usage:
# evidence = ocean_evidence("USLAX")
# Attach 'evidence' JSON to your AP invoice record

For both snippets, harden with exponential backoff on transient timeouts, and implement circuit breakers to prevent cascading failures in your AP pipeline. Because FreightPulse responses share the same envelope, you can build a common fetch wrapper with standardized logging, metrics, and error translations for your reviewers.

Real-World Use Cases: What finance and ops teams build with FreightPulse

1) Automated fuel-surcharge calculator for FTL invoices

A finance microservice ingests delivery events from the TMS, then calls /fuel-prices and calculates the fuel surcharge using the contract’s baseline and increment ladder. It adds the computed value, the diesel index, and the timestamp to the invoice header. If the carrier’s fuel line deviates by more than 2%, the invoice is queued for a quick manual review; otherwise, it’s auto-approved. Endpoints: GET /fuel-prices and GET /historical for audit trails.

2) Line-haul variance engine with spot benchmark

For spot or soft-contracted lanes, the engine requests a same-day freight quote via GET /freight-rates using the origin and destination ZIPs. It compares the invoiced line-haul to the market quote, flags variances above 10%, and attaches the quote JSON to the AP record. Over time, the team analyzes systematic deltas by corridor to renegotiate contracts or refine procurement triggers. Endpoint: GET /freight-rates.

3) Detention/demurrage adjudication using congestion and disruptions

When an invoice includes detention or storage fees, the adjudicator automatically checks GET /port-congestion with the relevant LOCODE and queries GET /disruptions filtered by the port. If congestion is “high” during the relevant week or a severe weather event overlaps the transit window, the rule engine can auto-approve or partially approve surcharges within defined caps. Endpoints: GET /port-congestion, GET /disruptions, plus GET /historical for a weekly congestion timeline stored for compliance.

4) Carrier compliance verification pre-payment

Before releasing payment, the AP system calls GET /carriers to validate the DOT number and legal name against the invoice. If status is not “active” or the legal_name mismatches, the invoice is halted for investigation. This step reduces fraud risk and compliance exposure with minimal engineering overhead. Endpoint: GET /carriers.

5) Forecasting accruals with fuel and congestion trends

Finance planning teams use GET /historical (diesel series) to project fuel surcharge exposure and GET /historical (port_congestion:<portid>) to anticipate detention/demurrage risk by trade lane. These projections feed monthly accruals and cash forecasting. Endpoints: GET /historical for both fuel and congestion.

Implementation best practices: reliability, governance, and observability

Building a reconciliation engine that finance can trust isn’t just about the right data—it’s also about resilient integration patterns and clear governance. Below are practical tips that map well to FreightPulse’s consistent response design:

Putting it all together: A reconciliation recipe

Here’s a streamlined recipe your team can adapt:

  1. Ingest delivered shipments nightly from your TMS, including origin/destination, pickup/delivery timestamps, planned miles, and invoiced amounts/fees.
  2. For each shipment, call GET /fuel-prices and compute the expected fuel surcharge per your contract’s baseline and increment ladder. Store the index value and computed surcharge.
  3. Fetch a lane benchmark using GET /freight-rates for the origin/destination pair. Compare to invoiced line-haul, compute variance, and apply thresholds to auto-approve or escalate.
  4. If the move touches a port, pull GET /port-congestion and GET /disruptions using the port’s LOCODE and delivery window. Attach findings and apply exception policies.
  5. Validate the carrier via GET /carriers against invoice header data (legal_name, DOT). If mismatched or inactive, hold payment pending investigation.
  6. Persist all evidence to your finance data store. Generate a concise settlement narrative for reviewers: “Fuel surcharge calculated from EIA weekly diesel average of $3.847/gal on 2026-07-30; line-haul within 5% of market; port congestion moderate (ratio 0.85) during week-of 2026-08-14; no high-severity disruptions; carrier active per FMCSA.”
  7. Emit metrics: auto-approval rate, average variance by lane, exception approval rate under congestion or disruption conditions, and cycle time to close. These inform policy refinement and contract negotiations.

Troubleshooting and error handling

Although FreightPulse normalizes responses, your finance pipeline should guard against edge cases:

By encoding these patterns, your automated reconciler becomes both resilient and auditable.

Complete, multi-endpoint example: building an evidence payload

Let’s assemble a full JSON evidence payload your AP system could store with each invoice. This example demonstrates how you might combine outputs from fuel, rates, congestion, disruptions, and carrier verification. 

{
"invoice_id": "INV-2026-008912",
"shipment_id": "SHP-001234",
"lane": {
"origin_zip": "10001",
"destination_zip": "90210",
"planned_miles": 2790
},
"carrier": {
"dot_number": 54283,
"lookup": {
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}
},
"fuel_surcharge": {
"index_source": "EIA (U.S. Energy Information Administration)",
"effective_timestamp": "2026-07-30T12:00:00Z",
"diesel_national_avg": 3.847,
"contract_baseline": 1.25,
"increment_per_10c_cents_per_mile": 0.5,
"calculated_amount_usd": 42.32
},
"linehaul_benchmark": {
"quote": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
},
"variance_vs_invoiced_pct": 4.7
},
"context": {
"port_congestion": {
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"as_of": "2026-08-14",
"congestion": "moderate",
"ratio_vs_baseline": 0.85
},
"disruptions": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
},
"decision": {
"auto_approved": true,
"policy_notes": "Fuel surcharge within 2% tolerance. Line-haul variance under 5% threshold. Moderate congestion acknowledged; no high-severity disruptions impacting USLAX during delivery window."
}
}

This structure not only streamlines approvals but also provides a fully portable evidence pack for audits, internal reviews, and mutual resolution with carriers.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices are sourced from the EIA weekly updates and exposed with a timestamp in the response. Use the timestamp as your effective date of record, and store it alongside your computed surcharge for a defensible audit trail.

Can I look up ocean carriers as well as trucking carriers?

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean NVOCC/OTI lookups (FMC directory) by toggling the type parameter. Air returns available:false, so build guards accordingly in your reconciliation flow.

Does the port congestion data reflect real-time vessel wait times?

No. Port congestion is a lagged approximation (~6–7 days) derived from IMF PortWatch AIS data, reported as a 7-day average vs a 90-day baseline. It is designed for finance-grade context and policy decisions, not live berth ETAs or real-time queue lengths.

Can I use FreightPulse to justify surcharge approvals during severe weather?

Yes. The /disruptions endpoint consolidates natural hazards from GDACS, USGS, and NOAA/NWS and supports port-radius filtering. Use type and severity to align with your exception policy and attach the normalized JSON as documentary evidence.

How do I benchmark a US FTL lane during reconciliation?

Call /freight-rates with mode=trucking, origin_zip, and destination_zip to retrieve an FTL quote. Compare price_usd to the invoiced line-haul and apply your variance thresholds for auto-approval versus manual review.

Conclusion + Call to Action

Reducing billing disputes isn’t about more spreadsheets—it’s about unifying the evidence. When your reconciliation engine can compute fuel surcharges from authoritative indices, benchmark line-haul against live market quotes, anchor exceptions in congestion and disruption context, and validate carriers in-line, most of the ambiguity disappears. Finance stops firefighting and starts approving with confidence. Carriers spend less time defending invoices and more time moving freight.

FreightPulse brings the critical pieces of that evidence together behind one stable REST API, with a consistent JSON envelope, practical coverage for finance scenarios, and the right level of lag-aware context for defensible approval policies. From your first prototype to a production-ready reconciliation service, it’s the fastest path to fewer disputes and faster close.

Build your settlement evidence pipeline today with FreightPulse, and see how a single, consolidated API can streamline carrier settlement. Try FreightPulse for free and ship your first automated reconciliation within days, not months.