Client Transaction Correlator — Help

The Client Transaction Correlator is a local desktop tool that matches a SimplePractice client export with a card transaction export, then creates a workbook for ZIP-level and apportionment review. It runs entirely on your computer — it does not upload client files or transaction data.

Exporting from SimplePractice

Save both files somewhere easy to find, such as Downloads or a folder for the tax year.

Export card transactions

1. Log in to SimplePractice.
2. Click Billing in the left sidebar.

3. Click Card Transactions.

4. Click the date field.
5. Choose Last Year for a prior-year tax report.
6. Click Apply if SimplePractice asks you to apply the date range.

7. Click Export transactions.
8. Save the exported file.

SimplePractice may prepare the export in the background and ask you to come back to download it when it is ready.

Before using the file, confirm that the report covers the intended tax year. The app will also try to read the transaction dates and add a note such as Transactions were dated from January 1, 2025 to December 31, 2025.

Export the full client list

The client file must include clients you are no longer actively seeing. If the export only includes active clients, older transactions may not match.

Don't skip this: the client export must include inactive and archived clients, not just active ones — otherwise transactions from former clients are left unmatched.

1. In SimplePractice, click Analytics in the sidebar.

2. Click Reports.

3. In the Clients and Appointments area, click Client Details.

4. Find the client status filter.
5. Select Active, Inactive, and Archived.
6. Click Apply.

7. Click Export.
8. Select CSV.
9. Save the exported file.

Required columns

The app is currently configured for these SimplePractice-style column names.

File	Expected columns
Client details	Client, Zip (optionally City)
Transaction report	Client Name, Amount, Net, Transaction Type

The client details file may also include City. When a matched client has no usable ZIP code, the app can use City = Portland to place the transaction in a Portland bucket. Matched clients with another city and no usable ZIP are placed in Not Portland.

Common export mistakes

• Exporting only active clients instead of active, inactive, and archived clients.
• Exporting year-to-date transactions when the tax report needs last year.
• Selecting the client details file where the transaction file belongs, or vice versa.
• Leaving ZIP codes blank or using placeholder values such as --.
• Editing the exported files in a way that changes the column names.

Using the app

The desktop app creates a local Excel workbook that summarizes transaction income by ZIP code and apportionment category. It does not upload files or use the internet during normal operation.

Basic run

1. Open Client Transaction Correlator.
2. Click Choose next to the client details file.
3. Select the full client details export from SimplePractice.
4. Click Choose next to the transaction report.
5. Select the card transaction export from SimplePractice.
6. Click Save As next to the output workbook.
7. Choose where to save the generated Excel file.
8. Click Run report.

The default output filename is:

deidentified-zip-codes.xlsx

When the run finishes, the app shows Done Processing. It may also show review notes or a list of clients who need ZIP codes added to the client file.

Reset and run again

Use Reset if you want to run another report while the app is still open. Reset clears selected files, output paths, advanced options, status messages, errors, and review panels.

Advanced options

Advanced options are hidden by default.

The full debug workbook adds detailed matching sheets, including unmatched transactions and match diagnostics. Use this when a transaction is not matching and you want to see why.

The de-identification option creates versions of the input files with client names replaced by stable anonymous codes. The same client receives the same anonymous identity in both files.

Understanding the output workbook

The production workbook is designed to show where transaction income belongs for ZIP-level and market-based sourcing review. It includes three sheets: Apportionment, Zip Totals, and Notes for Tax Preparer. The Apportionment sheet is first because it is usually the main tax-review sheet.

Apportionment

The Apportionment sheet summarizes net income by tax-relevant categories. Current categories include:

• Portland
• Multnomah
• Trimet
• Oregon
• Not Portland
• Not Oregon
• Unmatched
• Total Net

Some categories overlap. For example, a ZIP code can be in Oregon, Multnomah County, Trimet, and Portland at the same time. Because of that overlap, category percentages are not expected to add up to 100%. The Unmatched category includes transactions that could not be assigned to a usable ZIP or category.

Zip Totals

The Zip Totals sheet summarizes total gross and total net by ZIP code or bucket. It includes the ZIP code or bucket name, total gross, total net, client count, and transaction count.

The sheet includes an Unmatched row when transactions could not be matched to a client ZIP. This is intentional: all non-payout transaction amounts should be represented in the ZIP totals.

Notes for Tax Preparer

The Notes for Tax Preparer sheet contains no client names. It can include the transaction date range, matched and unmatched transaction counts, negative payout rows skipped, and high-level warnings about the input files. This sheet is meant to help a tax preparer review whether the inputs look like the correct files and date range.

Payout handling

Heads up: negative payout rows are excluded from totals — a row counts as a payout only when Transaction Type is payout and Amount or Net is negative. Negative non-payout rows stay in the report.

Troubleshooting

The app tries to warn you when the selected files look unusual. These warnings are review notes, not proof that something is wrong.

If many transactions are unmatched

First check the client details export. The most common cause is exporting only active clients. The client details file should include active, inactive, and archived clients. If a former client has transactions in the selected year but is missing from the client details file, those transactions may become unmatched.

If clients need ZIP codes

After a run, the app may show:

Please add zip codes to these clients

This means the transaction matched to a client record, but the client record has a blank, missing, placeholder, or non-numeric ZIP value. Fix the ZIP code in the client details source system or export, then export the client details file again and rerun the report.

If the date range looks wrong

The app attempts to read transaction dates and report the date range. Review the run notes if the app says the transaction report looks year-to-date, the date range is shorter than a full year, or no transaction date column was found. For prior-year tax reporting, the transaction export usually should cover January 1 through December 31 of the tax year.

If the wrong file was selected

The app checks for likely file swaps. For example, it may warn or stop if the client file looks like a transaction report or the transaction report looks like a client file. If this happens, choose the files again — the client details file is the full client list export, and the transaction report is the card transaction export.

Matching rules

The app matches conservatively. It tries, in order:

1. Exact client or account ID, when available.
2. Exact normalized client name.
3. A single partial name match.
4. Middle-name-compatible matching.
5. Couple names with & or and.
6. Description or memo fallback when exactly one client name is found.

If multiple possible clients remain ambiguous, the transaction is left unmatched instead of guessing.

Privacy and local-only use

Local only: during normal use the app never uploads files, sends client names or transaction data to a server, calls web APIs, uses cloud processing, or sends telemetry.

The app is designed for local handling of sensitive client and transaction data. It reads local files you select and writes local output files where you choose to save them.

De-identified files

The advanced de-identification option can create test files without client names. The anonymized files replace client names consistently across both input files, keep matching behavior useful for troubleshooting, remove transaction metadata columns such as Transaction ID and Source, and clear description or memo fields when present. Save de-identified files somewhere outside the app package, such as a normal documents folder or project folder.

Public help pages

These help pages should include only instructions and SimplePractice interface screenshots. Do not publish exported client spreadsheets, transaction reports, generated workbooks, or test data unless they have been separately reviewed for PHI.

Notes for tax preparers

The output workbook is intended to help review income sourcing by ZIP code and tax-relevant apportionment categories. Normal production output includes the Apportionment, Zip Totals, and Notes for Tax Preparer sheets. The Notes for Tax Preparer sheet avoids client names.

Apportionment categories

The apportionment summary currently includes Portland, Multnomah, Trimet, Oregon, Not Portland, Not Oregon, Unmatched, and Total Net. The categories can overlap. A single ZIP may belong to more than one category, so the category percentages should not be treated as mutually exclusive unless the tax method being applied requires a separate allocation formula.

Unmatched income

Unmatched income is intentionally preserved in the output. An Unmatched row can represent transactions where the client was not present in the client details export, the client record had no usable ZIP code, the transaction name was ambiguous, or the ZIP value was blank or non-numeric. The purpose is to keep all non-payout transaction income visible for review rather than silently dropping it.

Date range review

The app attempts to read the transaction date column and record the earliest and latest transaction dates. Review this note to confirm the report covers the expected tax period.

Payout rows

Negative payout rows are excluded from totals when Transaction Type is payout and either gross or net is negative.