---
name: "freight_invoice_audit"
description: "Audit freight invoices against contracted rates: recompute linehaul, discount, and fuel surcharge, check accessorials, weight, density and freight class, catch duplicate billing, and build the overcharge claim file carriers pay. Triggers when an invoice needs checking before payment, a carrier balance due bill arrives, a reweigh or reclass charge appears, or past paid invoices need a recovery audit."
---

# Freight Invoice Audit

## Purpose

Check a freight invoice against the deal that actually governed the shipment, find the charges that do not hold up, and turn each one into a claim with evidence attached. The skill covers LTL, truckload, and parcel invoices. It ships an audit checklist, a 16 code error taxonomy, a recomputation tool, and worked claim examples. It does not give legal advice. Deadline and liability calls on a disputed claim go to counsel or the carrier contract administrator.

## Workflow

1. **Pin the governing deal first.** Collect the pricing agreement and rate sheet in effect on the ship date, the carrier rules tariff version, any lane quote, the fuel schedule, the accessorial list with rates, and the minimum charge clause. If the deal cannot be found, stop and say so. An audit without the rate sheet is a guess, and guesses do not get paid back.

2. **Match the invoice to one shipment.** Confirm carrier, PRO number, bill of lading number, ship date, payer and account, origin, and destination against the shipment record. An invoice that matches no shipment, or matches a shipment already invoiced, is a finding before any math starts. Run the dedupe check in step 6 on every batch.

3. **Rebuild the shipment facts.** Take weight, dimensions, packaging, and commodity description from the bill of lading and the warehouse record, not from the invoice. For a palletized shipment, pallet dimensions and pallet weight count. Compute density and check the class. Density in pounds per cubic foot equals total weight divided by cubic feet, and cubic feet equals length times width times height in inches divided by 1728. Worked check: a pallet at 48 by 40 by 28 inches and 110 pounds is 31.11 cubic feet and 3.54 pounds per cubic foot, which sits in the 2 to under 4 band. For commodities on the full density scale with no special handling, stowability, or liability traits, that band is class 250. Confirm the NMFC item for the commodity before treating a band class as the billed class. Classes run 50 to 500 and turn on density, handling, stowability, and liability. Details: `references/error-taxonomy.md` codes E04 to E06.

4. **Recompute the expected charge, line by line.** Gross linehaul equals the rate per hundredweight times billable weight divided by 100. Net linehaul equals gross times one minus the discount percent. If the net is below the contracted minimum, the minimum replaces it. Billable weight is the greater of actual weight and dimensional weight when the contract applies dimensional pricing. Dimensional weight equals length times width times height in inches divided by the divisor named in the contract or carrier rules. Divisors vary by carrier and service, so never assume one. Fuel surcharge takes two forms. Percent form: the percentage from the contract fuel table for the named index, region, and week, applied to the net linehaul. Per mile form: current diesel price minus the baseline price, divided by the contract miles per gallon figure, times paid miles. Add only accessorials that pass step 5. Use `bin/freight_audit.py` so the arithmetic is printed and checkable.

5. **Put every accessorial through three gates.** Gate one, contracted: the charge and its rate appear in the agreement. Gate two, authorized: someone requested it for this shipment, or the shipment conditions in the agreement trigger it. Gate three, performed: the delivery record proves it happened. A liftgate charge at a delivery with a dock and a forklift on site fails gate three. Detention and demurrage also need the free time clause plus gate or appointment times that show the free time actually ran out. A charge that fails any gate is a finding, coded E08, E09, E10, or E11.

6. **Check duplicates and prior payments.** Group the batch by carrier, PRO or bill of lading number, and total. Same key twice is E01 until one copy is proved to be a corrected rebill that voids the first. Check the payment history too. A duplicate that was paid twice is a refund claim, not a credit note request.

7. **Check the clock before you check anything else on a late bill.** Under 49 USC 13710(a)(3)(B), a shipper must contest an original or subsequent bill within 180 days of receipt to keep the right to contest it. Under 49 USC 13710(a)(3)(A), a carrier must issue a bill for charges beyond those originally billed within 180 days of receipt of the original bill to collect them. Record the receipt date of every bill on the day it arrives. Contracts and carrier rules can impose shorter dispute windows, so work to the shortest window in the file. Keep cargo loss and damage claims out of this workflow. They run on a separate track with separate filing rules.

8. **Classify each variance.** Recoverable error: the billed amount conflicts with the governing deal or lacks the proof the deal requires. Data fix: the shipment was described wrong on the bill of lading and the carrier record is right, so pay it and fix the source data. Valid charge: it recomputes clean and passes all three accessorial gates. Never file a claim on a data fix. It burns credibility the next real claim needs.

9. **Build the claim file.** One shipment per claim unless the carrier accepts batch claims in writing. Packet order, cover letter template, and tracking rules: `references/claim-file.md`. The letter states the amount billed, the correct amount, and a specific amount claimed, line by line with the error code, the contract basis, and the shipment record for each line. If a carrier denies a line with no basis given, ask in writing for the rate, classification, rules, and practices the billed rate is based on. Under 49 USC 13710(a)(1) a motor carrier must provide that copy on request.

10. **Report and fix the cause.** Close with totals billed, totals verified, findings by code, amount claimed, amount recovered, and the root cause for any code that repeats. A code that repeats on one lane, one carrier, or one product is a process fix, not a pile of claims: wrong default class on a product master, a missing dock note that triggers liftgate billing, a fuel table nobody updated.

### Recomputation tool

Density and band class:

```bash
python3 ~/workspace/skills/freight-invoice-audit/bin/freight_audit.py density --length 48 --width 40 --height 28 --weight 110
```

Output: 31.1111 cubic feet, 3.5357 pounds per cubic foot, density band class 250, with the note that the band applies only to full density commodities with no special traits.

Expected charge from a JSON terms file with rate_per_cwt, weight_lb, discount_pct, minimum_charge, fsc_mode, fsc_pct or the per mile fields, optional dims_in and dim_divisor, and accessorials:

```bash
python3 ~/workspace/skills/freight-invoice-audit/bin/freight_audit.py calc terms.json
```

Compare one billed invoice against its terms, and find duplicates in a batch:

```bash
python3 ~/workspace/skills/freight-invoice-audit/bin/freight_audit.py check invoice.json
python3 ~/workspace/skills/freight-invoice-audit/bin/freight_audit.py dedupe batch.json
```

### Worked example: one invoice, two errors

Terms: rate $42.50 per hundredweight, weight 1,100 pounds, discount 65 percent, minimum $95, fuel surcharge 32.5 percent of net linehaul, one contracted accessorial, liftgate at $85.

Recomputation: gross linehaul $467.50, net linehaul $163.62, fuel surcharge $53.18, liftgate $85. Expected total $301.80.

Billed: linehaul $163.63, fuel surcharge $60.00, liftgate $85, plus inside delivery at $150, total $458.63.

Findings: E07, fuel surcharge over by $6.82, the billed figure matches no band in the contract fuel table for that week. E08, inside delivery at $150 is not in the contracted accessorial list and no one requested it. Variance claimed: $156.83. Claim packet: cover letter, recomputation sheet, invoice, bill of lading, proof of delivery showing dock delivery, contract rate page and fuel table, accessorial list page.

## Output Contract

Every audit run produces:

- A match record for each invoice: carrier, PRO, bill of lading, ship date, payer, and the shipment it matched, or a no match finding.
- A recomputation sheet per disputed invoice: gross linehaul, discount, net linehaul, minimum check, billable weight basis, fuel surcharge with its index, region, week, and formula, and each accessorial with its gate results.
- A findings list tagged with the taxonomy codes in `references/error-taxonomy.md`, each with billed amount, correct amount, variance, and the evidence that proves it.
- A duplicate report for the batch, with paid status for each duplicate.
- A deadline note per invoice: bill receipt date, the 180 day contest date under 49 USC 13710, and any shorter contract window.
- Claim files ready to send, one per shipment, built to `references/claim-file.md`, plus a claim log with follow up dates.
- A summary: totals billed, verified, claimed, and recovered, findings by code, and one root cause fix for any repeating code.

## Operating Rules

1. No rate sheet, no audit. If the governing agreement, fuel schedule, or rules tariff cannot be produced, report that as the result and stop. Do not rate an invoice from a quote screenshot or from memory.
2. Verify every number from a source in the file: contract, bill of lading, delivery record, index printout, or payment history. A figure with no source is cut, not estimated.
3. Use the agreement in effect on the ship date. Rates, discounts, fuel tables, and NMFC items change, and a current sheet proves nothing about a shipment from last quarter.
4. Separate the three tracks and never blend them in one letter: overcharge claims, carrier balance due disputes, and cargo loss or damage claims.
5. Pay the valid part. Dispute lines, not whole invoices, unless the whole invoice is a duplicate or matches no shipment. Holding a clean linehaul hostage over one bad accessorial weakens the claim.
6. File early. The 180 day federal contest window is a backstop, not a schedule. Work to the shortest window in the contract or carrier rules.
7. Keep the receipt dates, the claim log, and every carrier reply. A claim with no log entry does not exist when the carrier asks about it three months later.