Use Claude Code to Plan a Dry-Run Invoice Reconciliation Script

An invoice reconciliation script can be useful and still be wrong in a quiet way. It may match on the wrong field, treat a partial payment as settled, or overwrite the source file while you are still checking the rules.

This guide uses Claude Code to plan a small, local dry-run utility. The files and outputs are fictional. The workflow is documentation-based, not a recorded Claude Code run, and it does not claim accounting accuracy.

What you will make

You will prepare a proposed exception report from two CSV files:

invoices.csv: invoice ID, customer, amount, and due date.
payments.csv: payment ID, invoice ID, amount, and payment date.

The proposed report will show fully paid, partially paid, unpaid, and unmatched payment rows. It will not edit either CSV, send reminders, or post entries to an accounting system.

Prerequisites

You need Claude Code in a terminal, IDE, desktop app, or browser surface. The official overview says available surfaces and access requirements vary.

Use a disposable folder with no credentials. Keep this exercise separate from production accounting data. A finance owner should approve the matching rules before anyone uses a real file.

1. Create the fictional inputs

Create invoices.csv:

invoice_id,customer,amount,due_date
INV-101,Northwind,1000,2026-09-15
INV-102,Acme,750,2026-09-20
INV-103,Contoso,500,2026-09-25

Create payments.csv:

payment_id,invoice_id,amount,payment_date
PAY-201,INV-101,1000,2026-09-10
PAY-202,INV-102,300,2026-09-19
PAY-203,INV-999,200,2026-09-21

The expected illustrative classification is: INV-101 fully paid, INV-102 partially paid, INV-103 unpaid, and PAY-203 unmatched. These classifications follow the sample and rule below. They are not generated by Claude Code.

2. Start with a plan-only request

Open Claude Code in the disposable folder. Use its documented plan mode:

claude --permission-mode plan

Paste this request:

Plan a local, read-only invoice reconciliation utility for the two CSV files in this folder.

Rules:
- Match payments to invoices by invoice_id.
- Sum payments by invoice_id before comparing with invoice amount.
- Classify an invoice as fully_paid when total payments equal amount,
  partially_paid when total payments are greater than zero but lower than amount,
  and unpaid when there are no matched payments.
- Report overpaid invoices separately when payments exceed amount.
- Report payment rows whose invoice_id has no matching invoice.
- Preserve all original values and never edit, delete, rename, or overwrite files.
- Do not use the network, environment secrets, external packages, or an accounting connector.
- Propose a dry-run command and tests for the four classifications in the sample.

Return the proposed files, formulas, commands, and acceptance checks. Do not create files or run commands yet.

The useful output at this stage is a plan and a proposed exception schema. It is not a reconciliation result.

3. Review the proposed artifact

Ask Claude Code to review its plan:

Review the plan against these acceptance checks.

1. Every invoice in invoices.csv appears once in the invoice report.
2. Every payment row is either matched or listed as unmatched.
3. Partial payments are not labelled fully paid.
4. Overpayments are not hidden inside a paid label.
5. The original CSV files remain unchanged.
6. The report shows the source invoice_id and payment totals for each classification.
7. No network, credentials, external writes, or accounting-system actions are proposed.

Return a check table and list every unresolved assumption. Do not run the utility.

Stop if the plan silently treats an unmatched payment as an invoice, rounds money without a written rule, or writes into the input folder. Ask the finance owner to resolve those assumptions first.

4. Keep the first run dry

After approval, ask for a local dry-run implementation that writes only to a new report file, such as reconciliation-report.csv. Before running it, inspect the diff and confirm that the inputs are opened read-only.

A useful report schema is:

invoice_id,invoice_amount,payment_total,status,source_payment_ids,review_reason

For the sample, the illustrative rows should include INV-101 as fully paid, INV-102 as partially paid, and INV-103 as unpaid. PAY-203 should appear in a separate unmatched-payments section or report, not disappear because its invoice ID is unknown.

Troubleshooting

The plan edits the source CSV: stop and require a new output path. A dry run must preserve the inputs.
An invoice appears twice: check whether the implementation emits one row per payment instead of grouping by invoice_id.
An unmatched payment disappears: compare every payment ID in the input with the output. Unknown invoice IDs need an explicit exception.
Money totals differ: check decimal handling and rounding rules before changing the prompt.
The tool wants credentials or a connector: remove that step. The fictional exercise is local and read-only.

Limits and safe use

This workflow does not replace accounting controls, reconciliation policy, or an approval process. Do not use a generated report to post entries or contact a customer until a responsible owner checks the source rows, matching rules, currency, rounding, and exceptions.

TRY the plan with fictional CSVs. SKIP production data and external connectors during the first pass. USE a real utility only after the rules, diff, tests, and output have been reviewed.

Evidence label

Documentation-based builder guide with fictional CSVs and illustrative classifications. No Claude Code execution, script output, accounting integration, or measured result is claimed.