Developer ToolsFree generatorPDF, Excel, Word exportUnited States

State Sales Nexus CSV Checker Python Script Generator

Most finance teams track economic nexus in a spreadsheet that someone refreshes once a quarter. This generator writes a short Python script that totals an ERP invoice export by ship-to state and flags states approaching your threshold, with no server or upload required.

Fill in

Export invoice lines from your ERP.

Generated code
Download:

nexus_check.py

import csv
from collections import defaultdict

THRESHOLD = 100000
WARN = THRESHOLD * 80 / 100.0

totals = defaultdict(float)
counts = defaultdict(int)

with open('sales_export.csv', newline='', encoding='utf-8-sig') as f:
    for row in csv.DictReader(f):
        state = (row.get('ship_to_state') or '').strip().upper()
        if not state:
            continue
        try:
            amount = float(str(row.get('net_amount', '0')).replace(',', ''))
        except ValueError:
            continue
        totals[state] += amount
        counts[state] += 1

print('State  Sales        Lines  Status')
for state in sorted(totals, key=totals.get, reverse=True):
    total = totals[state]
    if total >= THRESHOLD:
        status = 'OVER THRESHOLD'
    elif total >= WARN:
        status = 'WARNING'
    else:
        status = 'ok'
    print(state.ljust(6), format(total, ',.2f').rjust(12), str(counts[state]).rjust(6), ' ', status)

How to run

python nexus_check.py

# Export only the trailing 12 months of invoice lines.
# Net out credit memos so returns reduce the total.

This script totals what is in the CSV; it does not know state rules. Use a state-specific threshold (some states use 250,000 or 500,000), a correct look-back period and the right sales base (gross or taxable). Review with your tax advisor before acting on the output.

Automated nexus monitoring

Optional: we can discuss turning this script into a scheduled report from your ERP.

Optional. The tool and every export work without this. No spam.

How to use the script

Export invoice lines for the trailing 12 months from your ERP with at least the ship-to state and net amount. Enter the exact column headers from the CSV in the generator. Paste the generated code into nexus_check.py, put the CSV in the same folder and run it with Python 3. The output ranks states by sales and marks each as ok, warning or over threshold. Change the warning percentage to give yourself more lead time.

Preparing a clean export

The result is only as accurate as the data. Include credit memos as negative amounts, use ship-to rather than bill-to state, and standardize state codes to two letters. If you have drop shipments, decide whether they count toward the state of delivery.

  • One row per invoice line or invoice total, not both
  • Credit memos as negatives
  • Two letter state codes, no free text
  • Trailing 12 months or the state's measurement period

Limits of a simple script

A single global threshold does not match reality: Texas and California use 500,000, Alabama and Mississippi 250,000, and many states 100,000. Extend the script with a dictionary of state thresholds, or run it per state. States that also count transactions need the line count column, which the script already prints for review.

Frequently Asked Questions

Does this upload my sales data anywhere?

No. This page only generates the code text in your browser. The script runs on your own machine against your own CSV, so the data never leaves your environment.

Which Python version do I need?

Any current Python 3 release works. The script uses only the standard library modules csv and collections, so nothing needs to be installed.

Why does it flag a state that is not actually over its threshold?

Because it applies one threshold to all states and counts every row in the CSV. Adjust the threshold for the state, make sure the export covers only the measurement period, and confirm which sales count under that state's rules.

Can I add transaction counts to the test?

The script prints the line count per state, but invoice count may be what the state tests. Group by invoice number first if your export has multiple lines per invoice.

If you want nexus monitoring running automatically from live ERP data with alerts, Netray can build it as a read-only report or agent.