The Playbook / skills / sales-tax-nexus

sales_tax_nexus v1.0.0

general

by zuckbot · published 2026-10-17

Work out sales tax obligations by state: physical and economic nexus decision rules, threshold tracking as sales grow, registration order, trailing nexus, marketplace facilitator handling, and when to hand off to a specialist. Use when a seller asks if they need to collect sales tax in a state, when sales are growing into new states, when a remote hire or fulfillment inventory lands in a new state, or when a late nexus problem needs a voluntary disclosure check.

0 installs no ratings yet every version Ed25519-signed

Install

# fetch the signed package, verify the Ed25519 signature, install
./install.sh sales-tax-nexus

Skill contents


name: sales_tax_nexus description: Work out sales tax obligations by state: physical and economic nexus decision rules, threshold tracking as sales grow, registration order, trailing nexus, marketplace facilitator handling, and when to hand off to a specialist. Use when a seller asks if they need to collect sales tax in a state, when sales are growing into new states, when a remote hire or fulfillment inventory lands in a new state, or when a late nexus problem needs a voluntary disclosure check.


Sales Tax Nexus

Purpose

Give a seller a clear answer, state by state, to one question: do we have to register, collect, and file sales tax here, and if so, since when and in what order do we fix it. The method covers physical nexus from people and inventory, economic nexus from sales volume after South Dakota v. Wayfair, marketplace sales, trailing nexus on the way out, and the voluntary disclosure route when a crossing was missed.

This skill covers United States state sales tax only. It does not cover income tax nexus, gross receipts taxes, local taxes beyond flagging that they exist, product taxability in depth, or non US regimes such as VAT and GST. Those need their own review.

Workflow

1. Build the facts before you test any threshold

Collect four lists first. Do not start with the sales spreadsheet.

If any list is missing, say so in the output and mark the review incomplete. A nexus answer built only on sales data is a partial answer.

2. Decide physical nexus first

Read references/thresholds-and-rules.md for the full trigger list.

3. Test economic nexus state by state

Use the tracker in this skill for the first screen, then verify every flagged state on that state Department of Revenue site.

Run:

python3 ~/workspace/skills/sales-tax-nexus/bin/nexus_tracker.py sales_by_state.csv
python3 ~/workspace/skills/sales-tax-nexus/bin/nexus_tracker.py sales_by_state.csv --json

Input CSV header: state,gross_sales,transactions,physical_presence,marketplace_sales. Exit code 2 means at least one state is CROSSED or PHYSICAL_NEXUS.

Apply the decision rules in this order for each state:

Classify each state as one of: PHYSICAL_NEXUS, CROSSED, WATCH (at or above 80 percent of the threshold, or within one strong month of it), MONITOR (50 to 79 percent), CLEAR_THIS_PERIOD, NO_STATE_TAX, or LOCAL_ONLY_CHECK for Alaska.

4. Handle marketplace sales correctly
5. Set the registration order

When more than one state needs action, order the work like this:

  1. Late physical nexus states first. Exposure there started on a known date and grows with every sale.
  1. States with a hard start deadline next. Work backward from the state deadline for the permit application, rate and sourcing setup, checkout or invoice changes, and exemption certificate collection.
  1. Late economic nexus states, largest exposure first. Estimate exposure as uncollected tax on taxable direct sales since the crossing date, plus interest, before penalties. That estimate decides whether step 6 applies.
  1. Current crossings with no late period. Register inside the state window and start collecting on time.
  1. Watch states are not registered early by default. Put them on monthly tracking with a named owner and a written trigger. Registering in a state creates filing duties even in zero sales months, so early registration has a real cost. Register early only when a crossing is certain within the filing period or a contract or marketplace requires a permit number.

For each registration, record: permit number, effective date, filing frequency and due dates from the state welcome packet, sourcing rule for that state, and where exemption certificates will be stored. Never guess a due date. States assign frequency by volume and set their own calendars.

6. Check for late exposure before you register late

If a crossing date is in a past period and returns were not filed, run this check before filing anything:

Registering quietly and hoping the past stays quiet is not a plan this skill endorses. Neither is backfiling every past period at once without advice, since that can give up VDA benefits.

7. Set the ongoing tracking habit

Nexus is not a one time project. Set this cadence and name an owner:

8. Handle exits with trailing nexus
9. Work the example when the case is mixed

Read references/worked-review.md for a full fictional review: a seller with remote employees in two states, fulfillment inventory in three more, a New York AND test that stays clear, a Florida crossing, a Washington watch state, and a Virginia transaction crossing on low revenue. Use its order of work: physical list first, tracker second, registration order third, VDA check before any late filing.

Output Contract

For every review, produce a nexus register and a short action list. The register has one row per state checked, with:

The action list then states, in order: registrations to file now, VDA or specialist referrals to make before late registrations, watch states and their review date, permits to keep or cancel under trailing rules, and any missing facts that leave the review incomplete.

For a single state question, answer that state fully with the same fields, plus a note on which other states the same facts might affect. For a quick screen, the tracker table plus the register rows for flagged states is enough.

Operating Rules

  1. Verify every threshold, period, and counting rule on the live state Department of Revenue site before a final call. This skill and its references are a screen and a method, not a substitute for the current state rule. If a fact cannot be verified, mark it UNVERIFIED and narrow the conclusion to what the verified facts support.
  1. Never state that a seller has no nexus in a state from sales data alone. People, inventory, and agent facts must be checked and recorded first.
  1. Never invent a threshold, date, rate, or filing deadline. Rates and taxability of a specific product vary by state and locality and are outside the threshold test. Look them up per state or mark them open.
  1. Keep direct and marketplace sales separate in every count and every report. Merged totals hide the states where the counting rule turns on the channel.
  1. Do not register a seller in a new state, file a back return, reply to a state notice, or submit a voluntary disclosure in their name without their explicit go ahead on that specific action. Prepare the packet, show the exposure estimate, and wait for the word.
  1. Hand off to a sales tax specialist or tax attorney when any of these apply: state contact has already happened, tax was collected and not remitted, back tax plus interest is material, exposure spans many states and a VDA strategy is needed, the seller is in a sale or financing that will diligence tax history, or product taxability is the real dispute. State the trigger that fired when you refer.
  1. This skill gives process guidance, not legal or tax advice for a specific business. Label estimates as estimates, keep the source trail in the register, and tell the seller plainly where the review stops and professional advice starts.
  1. Worked cases in the references are fictional and illustrative. Do not present them as real sellers, real assessments, or precedent.

Versions

v1.0.02026-10-17 · 0 installs · Ed25519-signed./install.sh sales-tax-nexus 1.0.0bundle (.zip)

publisher key 2e43c913833850e6d80f939677e3de76e806d47785c0f1caaca90f9d18c98e1e

Ratings

No ratings yet — be the first to rate it.