Home → Blog

Finance teams at 3PLs and logistics operators live and die by the accuracy and timeliness of their accruals, invoices, and audit trails. Yet the actual cost drivers behind a truckload or container movement—fuel surcharges, lane-based market rates, port slowdowns that trigger accessorials, and carrier compliance states—are scattered across disconnected systems. The result is an error-prone, manual reconciliation workflow: exported carrier invoices in one tab, rate tables in another, fuel indexes in a third, and ad hoc emails about “weather delays” or “port congestion” that may or may not be real.

This post shows how to build an audit-ready carrier invoice reconciliation engine that your finance operations can trust. We will use FreightPulse, a single REST API that consolidates the data finance and operations teams need: national and regional fuel prices, live US full-truckload rate quotes, port congestion metrics, carrier verification data, and natural-disruption alerts. Our goal is simple: automate the matching of invoices to verifiable, time-stamped market and risk context, and archive those facts in a consistent JSON schema for clean auditability.

We will walk through endpoints that allow you to trace costs back to objective signals in one place, then show how to construct line-level reconciliation logic and attach data evidence to every discrepancy, waiver, and approval. If you run accruals, variance analysis, or closed-period audits for a 3PL or logistics platform, this guide gives you the building blocks to move from “we think these charges are fine” to “each charge is matched, cross-validated, and supported by immutable evidence.”

Introduction

Consider a common scenario: your 3PL receives a weekly batch of FTL invoices. Each invoice contains a base linehaul charge, a fuel surcharge, and occasionally detention or layover fees. Meanwhile, your finance ops team needs to validate—without friction—whether:

Without a unified data source, teams patch together spreadsheets and screenshots from different sites and paid feeds. This creates latency, inconsistent evidence, and risky exceptions. Auditors then have to reverse engineer the story from miscellaneous artifacts.

An audit-ready reconciliation engine pairs each invoice line item with verifiable external signals at time-of-transaction. The keys are coverage (the right data domains in one place), consistency (one JSON schema), and governance (repeatable lookups with logs of what data was consulted). FreightPulse provides these primitives through straightforward endpoints so your engineering team can deliver a finance-grade control surface in days, not months.

Why FreightPulse

FreightPulse consolidates multiple logistics intelligence domains behind one API, which matters for finance in four critical ways:

From a developer’s perspective, FreightPulse is also ergonomic. One base URL, simple query parameters, and JSON responses that consistently convey success, data, and error messages. This lowers integration time, reduces glue code, and makes it feasible to reconstruct the full rationale for every penny in a ledger.

Quick Start

Base URL: 


https://freightpulsehq.com/api/v1

Let’s make a first request to retrieve national and regional fuel prices. This is often step one in reconciling fuel surcharges against a contract indexed to the national diesel average. 


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

Sample JSON 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 for reconciliation:

Core Endpoints

1) GET /fuel-prices — Anchor for Fuel Surcharges

Endpoint path: 


/fuel-prices

Purpose and business value:

Key response fields:

Example cURL: 


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

Example response (complete): 

{
"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
}
}
}
}
}

Implementation notes:

2) GET /freight-rates — Market Validation for Linehaul Charges

Endpoint path: 


/freight-rates

Purpose and business value:

Key parameters:

Example cURL (FTL truckload): 


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

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 interpretation for finance:

Best practice:

3) GET /port-congestion — Context for Delay-Related Accessorials

Endpoint path: 


/port-congestion

Purpose and business value:

Key parameters:

Example cURL: 


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
}
}
]
}
}

Field interpretation:

Best practice:

4) GET /carriers — Compliance and Risk Gate

Endpoint path: 


/carriers

Purpose and business value:

Key parameters:

Example cURL (trucking lookup 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"
}
}
]
}
}

Field interpretation for finance and compliance:

5) GET /disruptions — Evidence for Natural-Hazard Exceptions

Endpoint path: 


/disruptions

Purpose and business value:

Key parameters:

Example cURL (high-severity events near USLAX): 


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"
}
]
}
}

Field interpretation:

6) GET /historical — Trend Context for Accruals and Forecasts

Endpoint path: 


/historical

Purpose and business value:

Key parameters:

Example cURL (30-day diesel series): 


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 }
]
}
}

Field interpretation:

Designing an Audit-Ready Invoice Reconciliation Engine

An audit-ready engine needs to do more than fetch data. It must encode deterministic rules and leave behind an evidence trail for each decision. Below is a recommended architecture and governance blueprint.

Data flow and control surface

Reliability, governance, and observability best practices

End-to-End Example: Reconciling a Single Truckload Invoice

Assume a Phoenix, AZ (85001) to Edison, NJ (08817) dry van FTL moved with pickup on 2026-08-24. The invoice shows:

Reconciliation steps:

  1. Carrier verification: Query /carriers?q=54283. Confirm status is “active” and capture safety_rating and legal_name to your evidence ledger. If status != active, hold payment and escalate.
  2. Market validation: Query /freight-rates?mode=trucking&origin_zip=85001&destination_zip=08817&pickup_date=2026-08-24. If FreightPulse returns price_usd around, say, $7,200–$7,400, compute variance vs. $7,450. If within threshold (e.g., 5%), auto-approve; otherwise route to an analyst.
  3. Fuel surcharge: Query /fuel-prices and read diesel.national_average as of the week of 2026-08-24 (use timestamp for week alignment). Apply contract formula (e.g., a base per-mile index and fuel surcharge per mile above a peg) and compute expected surcharge. Compare to $620; record variance.
  4. Detention claim: If movement involved a port leg or cross-dock near a port, call /port-congestion?port=USLAX or relevant port to assess systemic slowdowns in the period (remember these metrics are lagged approximations). Also call /disruptions?type=severe_weather&country=US or by port radius for the pickup date range. If no events match time and place, flag for operator review; else record event details and approve per policy.
  5. Archive evidence: Store all responses, include request URLs and parameters, timestamps, and computed decisions in your ledger. Create a PDF or HTML audit bundle if your auditors prefer human-readable attachments.

Implementation Snippets: Python and JavaScript

Python: validating fuel surcharge and linehaul side by side and storing evidence. 

import requests
import hashlib
import json
from datetime import datetime

BASE = "https://freightpulsehq.com/api/v1"

def fetch_json(url):
r = requests.get(url, timeout=15)
r.raise_for_status()
payload = r.json()
if not payload.get("success", False):
raise RuntimeError(f"API error: {payload.get('error')}")
return payload

def evidence_hash(payload):
return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()

# Example shipment context
origin = "85001"
dest = "08817"
pickup = "2026-08-24"
linehaul_billed = 7450.00
fuel_billed = 620.00

# 1) Fuel prices
fuel_url = f"{BASE}/fuel-prices"
fuel = fetch_json(fuel_url)
diesel = fuel["data"]["data"]["diesel"]["national_average"]
fuel_ts = fuel["data"]["timestamp"]
fuel_hash = evidence_hash(fuel)

# Example contract computation (replace with your formula)
# For demo: assume 2,400 miles, 6 mpg peg, surcharge = miles * (diesel - 3.00) / 6
miles = 2400
peg = 3.00
expected_fuel = max(0, miles * max(0, diesel - peg) / 6)

# 2) Freight rates market check
rate_url = f"{BASE}/freight-rates?mode=trucking&origin_zip={origin}&destination_zip={dest}&pickup_date={pickup}"
rates = fetch_json(rate_url)
market = rates["data"]["price_usd"]
rate_hash = evidence_hash(rates)

# Build reconciliation record
record = {
"shipment": {"origin_zip": origin, "destination_zip": dest, "pickup_date": pickup},
"linehaul": {
"billed": linehaul_billed,
"market_quote": market,
"variance_pct": (linehaul_billed - market) / market * 100.0,
"evidence": {"url": rate_url, "hash": rate_hash}
},
"fuel": {
"billed": fuel_billed,
"benchmark_diesel_usd_per_gal": diesel,
"benchmark_as_of": fuel_ts,
"expected": round(expected_fuel, 2),
"variance_pct": (fuel_billed - expected_fuel) / expected_fuel * 100.0 if expected_fuel else None,
"evidence": {"url": fuel_url, "hash": fuel_hash}
},
"created_at": datetime.utcnow().isoformat() + "Z"
}

print(json.dumps(record, indent=2))

JavaScript (Node.js or browser) for a disruption check tied to a port: 

async function fetchJson(url) {
const r = await fetch(url);
if (!r.ok) throw new Error("HTTP " + r.status);
const payload = await r.json();
if (!payload.success) throw new Error(payload.error || "API error");
return payload;
}

async function disruptionsNearPort(portLocode, severity) {
const url = `https://freightpulsehq.com/api/v1/disruptions?port=${encodeURIComponent(portLocode)}&severity=${encodeURIComponent(severity)}`;
const data = await fetchJson(url);
return data.data.results || [];
}

(async () => {
const results = await disruptionsNearPort("USLAX", "high");
console.log("Relevant events:", results.length);
for (const ev of results) {
console.log(`[${ev.severity}] ${ev.type}: ${ev.title} at ${ev.starts_at}`);
}
})().catch(console.error);

Error Handling and Troubleshooting

Every FreightPulse response follows a consistent envelope. When success is false, you receive a human-readable message in the error field. Implement centralized handling to convert these into actionable logs and UI messages.

Common error response shape: 

{
"success": false,
"error": "Human-readable message."
}

Examples and guidance:

Real-World Use Cases

Fuel Surcharge Calculator and Auto-Approval Engine

Finance teams can build a surcharge calculator that pulls the diesel national average each week from /fuel-prices and applies the contract formula to compute expected surcharges per lane-mile. When invoices arrive, computed vs billed is compared; if within tolerance, the line auto-approves with embedded evidence JSON. Endpoints used: /fuel-prices, optionally /historical for week-over-week forecasting.

Linehaul Variance Checker with Market Evidence

For each truckload invoice, call /freight-rates using origin/destination ZIPs and pickup date to get a contemporaneous market quote. If the billed linehaul diverges materially, trigger a review workflow and attach the quote with service type and expected transit window. Endpoints used: /freight-rates.

Disruption-Aware Accessorial Validation

When a carrier cites weather or port delays for detention, correlate the claim with /disruptions filtered by port or country and date, and with /port-congestion to understand background conditions. Auto-approve when relevant events are present; otherwise route to dispute handling. Endpoints used: /disruptions, /port-congestion.

Carrier Vetting at Invoice Time

Run /carriers for each invoice to confirm active status and safe operating profile. If the carrier is not in good standing at service time, escalate and block payment. Endpoints used: /carriers.

Accrual Modeling with Time Series

Use /historical to load a 90-day diesel series and, where relevant, port congestion trends for major ports tied to your network. This informs accruals and forward-looking expense plans, creating realistic expectations for finance reviews. Endpoints used: /historical (fuel_price_diesel_national, port_congestion:<portid>).

Performance Tips and Best Practices

Comprehensive Endpoint Coverage and Field-by-Field Guidance

/fuel-prices

/freight-rates

/port-congestion

/carriers

/disruptions

/historical

Additional Example Responses and Explanations

Freight rates with missing context producing an “available”: false state. Handle gracefully by prompting for required params. 

{
"success": true,
"data": {
"available": false,
"mode": "trucking",
"message": "Missing or incomplete lane parameters (origin_zip, destination_zip)."
}
}

Explanation:

Disruption query scoped by type and country for a specific audit window: 

curl "https://freightpulsehq.com/api/v1/disruptions?type=severe_weather&country=US"

Sample response (complete): 

{
"success": true,
"data": {
"results": [
{
"id": "nws:SW:2026-08-20:CA:LA",
"type": "severe_weather",
"severity": "high",
"title": "Severe Thunderstorm Warning - Los Angeles County",
"country": "United States",
"starts_at": "2026-08-20T22:15:00+00:00",
"source": "NOAA/NWS"
},
{
"id": "usgs:EQ:2026-08-19:36.1:-115.2",
"type": "earthquake",
"severity": "low",
"title": "M3.1 - 25km NW of Las Vegas, NV",
"country": "United States",
"starts_at": "2026-08-19T04:55:00+00:00",
"source": "USGS"
}
]
}
}

Using this:

Historical port congestion series for a major port (trend analysis): 

curl "https://freightpulsehq.com/api/v1/historical?metric=port_congestion:USLAX&period=90d"

Sample response: 

{
"success": true,
"data": {
"metric": "port_congestion:USLAX",
"period": "90d",
"series": [
{ "date": "2026-06-01", "value": 0.93 },
{ "date": "2026-06-08", "value": 0.90 },
{ "date": "2026-06-15", "value": 0.88 }
]
}
}

Interpretation:

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect updates that align with official benchmark publishing schedules. Responses include a timestamp; store it alongside your computed surcharge so auditors can see the exact benchmark used at the time of reconciliation.

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

Yes. The carriers endpoint supports trucking (DOT-number-based) and ocean NVOCC/OTI lookups in the same API. Pass the appropriate query and type parameter to retrieve the relevant results for your vendor verification workflow.

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

No. Port congestion is a lagged approximation: a 7-day average of port calls compared to a 90-day baseline, with about a 6–7 day data lag. It’s valuable context for finance decisions but should not be interpreted as real-time AIS queue measurements.

How should finance teams use disruption data for accessorial approvals?

Correlate event type, severity, and start time with shipment pickup and transit windows, preferably filtered by the relevant port or country. Use deterministic rules—e.g., auto-approve detention when a high-severity event overlaps—so your decisions are consistent and auditable.

What’s the best way to make this audit-ready?

Treat every decision as a function of structured inputs and attach the raw FreightPulse JSON, request URL, and a hash of the response to your evidence ledger. Implement role-based access, append-only logs, and stable weekly snapshots for close processes to ensure repeatable, defensible audits.

Conclusion + CTA

Carrier invoice reconciliation doesn’t have to be a maze of spreadsheets and subjective judgments. By consolidating fuel benchmarks, market rate quotes, port congestion context, carrier verifications, and natural-disruption evidence behind one API, finance teams can automate line-level decisions with clear, portable proofs. The result is faster closes, fewer disputes, tighter accruals, and a durable audit trail that scales with your network.

This post outlined how to wire FreightPulse into a reconciliation engine that finance trusts: use /fuel-prices to anchor surcharges, /freight-rates to benchmark linehaul, /port-congestion and /disruptions to validate exceptions, /carriers to verify vendors, and /historical to power accruals and forecasts. Wrap these in robust retries, logging, and governance—and you’ll have a system that de-risks audits and accelerates approvals.

Start building now with FreightPulse. Explore the endpoints, plug them into your reconciliation workflow, and attach the evidence to every invoice line. Ready to streamline your financial operations and elevate audit readiness? Try FreightPulse for free and ship your first production-grade integration today.