Vendor Recovery Engine

Amazon takes deductions from vendor payments: shortages, price claims, chargebacks. Many are wrong, and nobody checks them in time. This engine reconciles every deduction and payment against the vendor's own records and says, for each one, whether it can be disputed, why, and which file row proves it.

Results of one run on a synthetic world built on real public data · as of · source on GitHub · by Ney Fred Jiménez Campos

Where the money is

Recoverable now versus lost because the dispute window closed before anyone looked. Hover a bar for the numbers.

Recoverable nowPast the dispute window

File these first

Every claim has a deadline. The work queue puts claims whose dispute window closes within 30 days first, then ranks by expected value: amount times an assumed win rate for that kind of evidence (configurable priors, to be replaced by a vendor's own dispute history).

Window closes within 30 daysLater

Every deduction gets a verdict

Most deductions are valid and the engine says so. A claim is only made when the vendor's records prove it; when they can't, the finding says what is missing instead of guessing.

Look at one vendor

The largest claims for the selected vendor, each with the rule that decided it, the evidence, and the exact file and row it comes from.

Scored against ground truth

The generator records the right answer for every deduction it creates; the engine never sees it. This run used a seed that was never used during development.

When the evidence gets worse

The same underlying world, with more and more proofs of delivery missing and references truncated or mistyped, scored against what really happened rather than what the files can prove. Precision is the share of claims that are true; recall is the share of real money recovered.

Precision (claims that are true)Recall (real money recovered)

Dispute letters drafted by AI, checked by code

Claude drafts each letter from the facts of one finding (an offline template stands in when no API key is set). A deterministic verifier then requires every amount, document number and date in the letter to appear in those facts; a letter that fails is rejected. To prove the verifier works, each letter is re-checked with one error injected at a time.

Four real bugs the evaluation caught

A perfect score on its own benchmark proves consistency, not truth. The value of the benchmark showed when it failed:

Paid invoices that looked unpaid

Remittances quoting the PO number instead of the invoice number.

94.95 % precision, $88,757 in false claims → match payments by PO when that PO has a single invoice → 100 %, $0

European number formats

1.234,50 was read as 1.2345 with no error; 31.12.2025 dates were rejected.

98.01 % recall, $2,669 missed → detect the decimal separator per column, per file → 100 %

A typo two edits away

Removing leading zeros turned PO MJPYNQ05 into MJPYNQ5, so the typo MJPYNQ0V stopped matching. Found on the holdout run.

5 wrong verdicts hidden by a rounded "100.00 %" → fuzzy match on raw characters, print exact mismatch counts → 0 mismatches

An invented document number

The letter verifier only checked identifiers with digits; PO and shipment numbers can be all letters, so an invented QQUOGOZZ passed.

968 of 972 injected errors caught → any token with a digit, a hyphen or 8+ capitals must come from the facts → all caught

How it works

1 · IngestParquet, CSV and Excel; any header style; US and EU formats. Bad rows go to quarantine with the reason and line number.
2 · ValidateSchema contracts per table (pandera), shaped like the SP-API vendor models.
3 · MatchExact → normalized → digit suffix → one-typo fuzzy. Two candidates means review, never a guess.
4 · DecidePOD vs shortages, invoice vs PO cost, ship dates vs windows, ECB rates vs applied FX, reversals, duplicates, deadlines.
5 · ReportExcel workbook, PDF summary and a dispute-ready CSV per vendor, every line traceable.

What is real and what is synthetic

Real public data
  • UCI Online Retail II (CC BY 4.0): 1.07M real transaction lines → product catalog, unit costs, order quantities, cancellation rates.
  • ECB reference rates: real daily EUR, GBP, CAD, MXN and JPY rates for every FX check.
  • Amazon SP-API vendor models: column names and shapes for orders, shipments and invoices.
Synthetic, with known answers
  • 170 vendors (made-up names: no real company is attached to a fabricated claim).
  • Deductions, remittances and proofs of delivery, with discrepancies injected on purpose and recorded in a ground-truth table.
  • Real-world mess: mixed formats, glued exports, duplicated rows, truncated and mistyped references.