Freight Fuel Surcharge Check

Review fuel charges against the right dated percentage and the right charge base. This Actor compares shipment-level fuel amounts with supplied rate schedules, includes only explicitly fuel-eligible components, and returns calculation differences with the rate reference behind them.

For shipping finance teams and freight bookkeepers, it provides a repeatable second check before investigating a carrier bill. It does not infer contract terms, retrieve live tariffs, contact carriers or promise recoveries. An unresolved shipment remains unresolved rather than receiving an assumed zero rate or a false match.

Who should use it?

Use this when you already have structured shipment charges and an authorized percentage-based fuel schedule. Suitable users include e-commerce shipping teams reviewing parcel invoices, freight bookkeepers checking weekly exports, and logistics analysts building a pre-payment review workflow.

It is not a full freight-audit service. If you need PDF interpretation, freight-class analysis, carrier disputes or contract negotiation, use an appropriate broader service. This Actor focuses on a specific calculation that can be repeated across a bounded batch without changing your existing systems.

Key features

• Matches carrier, service, contract date basis and inclusive effective-date interval.
• Uses explicitly classified charge components, so nonfuel charges do not automatically inflate the base.
• Applies a percentage once to the summed eligible base using integer arithmetic and half-up cent rounding.
• Preserves signed differences: billed above and billed below calculation are distinct.
• Flags missing dated rates and unconfirmed contract rules as unresolved.
• Keeps unresolved shipments visible and excludes them explicitly from compared totals.
• Rejects overlapping rate intervals and contradictory duplicate IDs instead of choosing arbitrarily.
• Reviews up to 2,000 shipments and 500 dated schedule rows per report.

Practical examples

A merchant can check whether a new weekly export used the selected fuel percentage for each shipment date. A bookkeeper can see whether an accessorial was included in the declared fuel base. A logistics analyst can review invoice-date-based and shipment-date-based contracts separately without silently mixing them. An automation developer can route unresolved shipments to a human instead of treating incomplete inputs as approved bills.

These are potential workflows, not claims about errors at any particular carrier or customer. Published carrier schedules are evidence that rates vary; the actual contract determines which rules apply to your account.

Quick start

1. Identify your contractual percentage-based fuel model, eligible components, date basis and rounding rule.
2. Supply the applicable dated rates and a stable source reference for each. Rates are not downloaded by this Actor.
3. Supply shipment charges with explicit fuelEligible flags. Exclude the fuel surcharge itself from the calculation base.
4. Set basisConfirmed and componentsComplete truthfully. Use false when the contract or component coverage is unresolved.
5. Run the Actor and review findings together with unresolved, not just the net total.

Only use the comparison where the contractual model is a percentage applied once to the eligible shipment base, rounded half-up to cents. Other rounding or fuel models are outside scope.

The prefilled example is invented data with one deliberate difference. A completed demonstration is billable.

Input example

{
  "currency": "USD",
  "rateRows": [{
    "id": "R-DEMO",
    "carrier": "CARRIER-DEMO",
    "service": "GROUND",
    "validFrom": "2026-10-05",
    "validThrough": "2026-10-11",
    "percent": "30.25",
    "dateBasis": "shipmentDate",
    "sourceUrl": "https://example.org/fuel-rates"
  }],
  "shipments": [{
    "id": "S-DEMO",
    "carrier": "CARRIER-DEMO",
    "service": "GROUND",
    "shipmentDate": "2026-10-09",
    "invoiceDate": "2026-10-12",
    "dateBasis": "shipmentDate",
    "basisConfirmed": true,
    "componentsComplete": true,
    "components": [
      {"id": "TRANSPORT", "amount": "100.00", "fuelEligible": true},
      {"id": "OTHER", "amount": "20.00", "fuelEligible": false}
    ],
    "billedFuel": "36.30"
  }]
}

CARRIER-DEMO and example.org are fictional demonstration references. The percentage is an illustrative input, not a current carrier quote or a contract entitlement.

Input parameters

Input	Required	Rules
currency	Yes	One shared two-decimal currency: USD, CAD, EUR, GBP or AUD.
rateRows	Yes	1–500 schedule rows. No overlapping validity intervals for the same carrier/service/date basis.
shipments	Yes	1–2,000 shipment records, each containing 1–30 charge components.

Each rate row requires id, carrier, service, validFrom, validThrough, percent, dateBasis and sourceUrl. Dates must be real YYYY-MM-DD dates. Rate percentages are nonnegative decimal strings between 0 and 100, with at most four decimal places. Date basis is exactly shipmentDate or invoiceDate. Source URLs must be HTTPS without embedded credentials, query strings or fragments. The URL is a retained reference, not a fetched or authenticated source.

Each shipment requires id, carrier, service, both dates, dateBasis, basisConfirmed, componentsComplete, components and billedFuel. Confirm the base, date and supported rounding rules before setting basisConfirmed true. componentsComplete declares full component coverage for this review; it is not independently verified.

Each component has a unique id, nonnegative amount string with at most two decimal places, and boolean fuelEligible. Do not include the fuel charge itself as an eligible component. Supply the actual contractual net base after relevant discounts; the Actor does not apply discounts or determine eligibility automatically. Credits, returns, negative adjustments, minimum/maximum fuel charges and cents-per-mile models are unsupported.

IDs, carrier and service labels use 1–60 letters, numbers, periods, underscores or hyphens and are normalized to uppercase. Different representations of the same carrier should be mapped consistently before review. Do not use account numbers or personal information as IDs.

Output example

Selected fields from the verified result for the exact input above:

{
  "currency": "USD",
  "summary": {
    "uniqueShipmentCount": 1,
    "comparedShipments": 1,
    "unresolvedShipments": 0,
    "identicalDuplicatesIgnored": 0,
    "rateCount": 1,
    "findingCount": 1,
    "comparedBilledFuel": "36.30",
    "comparedExpectedFuel": "30.25",
    "signedComparedDifference": "6.05"
  },
  "reviewRequired": true
}

The full report includes rows, findings, unresolved, supplied rateRows, a check timestamp, an input fingerprint, coverage statements and the rounding model.

Output	Meaning
rows[].eligibleBase	Sum of explicitly eligible component amounts.
rows[].expectedFuel	Calculated value, or null when inputs do not establish a comparison.
rows[].difference	Billed minus calculated fuel, or null for unresolved rows.
findings	Nonzero calculation differences with shipment, rate ID and review action.
unresolved	Every shipment held for missing rules, incomplete components or unavailable dated rates.
summary	Counts and totals for compared shipments only; unresolved amounts are excluded explicitly.
coverage	Rates and contractual rules were not independently verified.

A signed total can hide offsetting differences. Inspect individual findings rather than interpreting a zero combined difference as no issues.

How it works

The Actor validates the entire input before producing output. It groups rates by carrier, service and date basis, rejects overlapping intervals, and selects the applicable interval for each shipment. It sums eligible component cents, applies the percentage once, then rounds half-up to the nearest cent. It compares that result with the supplied fuel charge.

Identical records under the same ID are counted and ignored. Conflicting uses of an ID fail. Equal amounts under different shipment IDs remain separate shipments. Missing contract confirmation, incomplete component coverage or a date without an applicable rate produce explicit unresolved rows. No rate is carried forward beyond its stated interval.

Pricing

Configured launch price: $0.45 per completed report, including up to 2,000 shipments and 500 rate rows. A report is one dataset item and one fuel-surcharge-review event. Reports containing differences or unresolved shipments are completed review work and are billable. Invalid input rejected before report creation does not trigger the event.

Actor event examples: one report $0.45; ten reports $4.50; 100 reports $45.00. Four weekly reviews cost $1.80 in Actor events. These examples do not establish customer savings. Applicable Apify plan/platform charges, retained storage and downstream access are separate; the Store pricing panel is authoritative. No contingency fee, per-finding fee or recovered-money percentage applies.

API and scheduling

Use the official Apify client to send a refreshed export:

import { ApifyClient } from 'apify-client';
import fs from 'node:fs';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = JSON.parse(fs.readFileSync('sample_input.json', 'utf8'));
const run = await client.actor('wheresprada/freight-fuel-surcharge-check').call(input);
const { value } = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');
console.log(value.summary, value.unresolved);

Install apify-client in your integration and save the tested JSON as sample_input.json. Keep API tokens in secure environment storage. A scheduled task can run after your authorized export workflow refreshes its input. Repeating an old snapshot does not fetch new rates or invoices. Completion webhooks can notify a downstream review queue; inspect the actual run status and unresolved records first.

Limits and accuracy

Input is capped at 2,000,000 UTF-8 bytes, with 128 MB memory and a 30-second runtime limit. Oversized requests fail without silently truncating shipments. This version supports only positive percentage-based models with the documented rounding rule and one shared currency. It does not verify tariff applicability, account-specific discounts, taxes, freight classification, weights, legal entitlement or recoverability.

A calculation difference is a review candidate, not a confirmed carrier error. Contract amendments, rounding, eligibility or date-basis mistakes in the supplied input may explain it. Rates and rules must be maintained by an authorized user or upstream process.

Privacy and security

No carrier login, proxies, paid external API or network retrieval is required by processing. Avoid uploading names, addresses, account numbers, credentials or entire commercial invoices. The provided inputs and resulting reports are held in Apify run storage according to its access and retention settings. No automatic deletion or security certification is promised. Source references and commercial amounts may be sensitive even without personal information; restrict their dataset links appropriately.

Troubleshooting and FAQ

Why is a shipment unresolved? Check its reason codes. Confirm the contract model, complete charge components and a matching dated rate. Unknown values are not treated as zero.

Why is my rate schedule rejected? Two intervals overlap for the same carrier, service and date basis, or an ID has conflicting records. Resolve those ambiguities first.

Can it download current carrier rates? No. Supply the applicable schedule from an authorized source. Published rates may not match your account contract.

Can I use cents per mile? No. This product checks percentage-based fuel models only.

Does a difference prove an overcharge? No. Review the contract and source records. The Actor performs calculations, not legal or commercial claims decisions.

Is an unresolved report charged? Yes, when a complete report was produced. Its explicit holds are the useful result. Invalid input does not trigger the report event.

Where are results? One complete report appears in the default dataset and under OUTPUT in the key-value store.

Support and source context

Report reproducible problems through this Actor's Apify Issues tab with a run ID and a redacted minimal example. Do not post invoices, account details or tokens publicly.

Carrier context: UPS fuel surcharges and effective-date history. Different services and contracts can use different rules. The Actor is independent and not affiliated with any carrier. Platform integration guidance is in the Apify documentation.