Multi-state tax engine design for fintech — domicile rules, convenience-of-employer, and the MA millionaires tax

The architectural assumption baked into most American tax software is that a taxpayer lives in one state. That assumption was always partly wrong. Since 2020 it has been thoroughly wrong: remote work has scattered earners across multiple states, several states have enacted aggressive sourcing rules, and the population of taxpayers with genuine domicile ambiguity has grown faster than tax-software vendors have re-architected their engines to handle it.

This guide is for engineering and product teams building tax engines, planning tools, or wealth platforms with a multi-state exposure surface. It walks through the rule families the engine has to evaluate, the data structures that determine whether the rules can be evaluated correctly at all, and the specific edge cases that separate an engine that handles the easy cases from an engine that survives an audit by a state revenue agency.

The four rule families

A multi-state tax engine has to answer four questions for any given taxpayer in any given year:

1. Where is the taxpayer domiciled? (Domicile is a single state, by definition; it determines where worldwide income is taxable as a resident.)
2. Where is the taxpayer a resident for tax purposes? (Residency can be plural and is statutory, not domicile-based.)
3. Where is each item of income sourced? (Sourcing rules are state-specific and often non-symmetrical.)
4. What is the credit-for-taxes-paid mechanism in the resident state? (Resident-state credit calculations are full of edge cases.)

These four questions are not independent. Domicile feeds residency feeds sourcing feeds credits, and a wrong answer at the top cascades. Engines that try to handle the four as parallel calculations rather than as a sequence with explicit dependencies produce subtle errors that compound across years.

Domicile — the single hardest determination in personal tax

Domicile is the state a taxpayer considers their permanent home and intends to return to. The legal standard varies slightly by state but typically rests on a multi-factor test: where the taxpayer's family is, where they vote, where their primary home is, where they bank, where they're licensed to drive, where they hold professional licenses, where they're buried — yes, plot ownership is on the New York test — where they keep heirlooms, and where they spend their time.

A few engineering implications:

• Domicile is not a checkbox. No single field on a tax return determines it. A taxpayer's "state of residence" line on the 1040 is the taxpayer's assertion of domicile, not the state's. Every state revenue agency reserves the right to disagree with the assertion and audit it.
• Domicile changes are events, not toggles. A state-of-domicile change requires a documented sequence: closing the prior domicile (selling the home, returning the driver's license, changing voter registration), opening the new one (purchasing or leasing the new primary residence, registering to vote, obtaining the new license, moving family).
• The 183-day rule is residency, not domicile. Most states impose statutory residency on taxpayers spending 183 days or more in the state, regardless of domicile. A taxpayer can be domiciled in Florida and statutorily resident in New York simultaneously — and owe state tax to both, with offsetting credits.

What your data model has to capture. A timeline of the taxpayer's days-by-state with date precision. A documented domicile assertion for each tax year. The supporting facts (residence, voting, licensing, family) per year. A change-event ledger when domicile asserted-changes occur.

Most engines we've reviewed handle "the taxpayer lives in California" cleanly and break the moment the taxpayer claims a Florida domicile while owning a Manhattan apartment.

The 183-day residency trap

State statutory residency rules are usually some variant of: "you're a resident if you spent more than 183 days here AND maintained a permanent place of abode here for the year." The two prongs are conjunctive — both must be true.

"Permanent place of abode" is a structural test. A hotel stay is not a permanent place of abode. A rented apartment with a year-long lease is. A spouse's apartment, owned by the spouse, that the taxpayer has access to, may or may not be — the case law is split.

Your engine has to track day-by-state with sub-day awareness. Travel-receipt integration, calendar integration, or an explicit data-entry workflow for taxpayers in residency-ambiguous situations. An engine without this is silently wrong for any high-income remote worker with multi-state exposure.

Sourcing — the convenience-of-employer rule

Income sourcing is the next layer down. For a wage earner, the basic rule is that wages are sourced to the state where the work is performed. Simple — except for the convenience-of-employer rule.

Several states (most aggressively New York, Connecticut, Pennsylvania, and Delaware, with variants in others) treat days a remote employee works from outside the employer's state as days "worked in" the employer's state if the remote work was for the employee's convenience rather than the employer's necessity. The result: a remote worker in Florida employed by a New York firm owes New York state tax on their full wages — even though they never set foot in New York.

This rule has been repeatedly upheld in litigation. Zelinsky v. Tax Appeals Tribunal established the doctrine in 2003; Edward A. Zelinsky v. Tax Appeals Tribunal reaffirmed it in 2024. New York's tax department has been increasingly aggressive about audits of out-of-state remote workers since the pandemic-driven population dispersal.

What this means operationally. Your engine has to capture, per employer, per work-day:

• Where the employee worked
• Whether the work-from-non-employer-state was for the employee's convenience or the employer's necessity
• The supporting documentation for the necessity claim (contractual remote-work designation, bona-fide office in the remote state, etc.)

Most W-2-only tax engines have no concept of any of this. The data simply doesn't exist in the W-2 — the W-2 reports state wages by the state the employer's payroll system associated them with, which may or may not reflect any of the rules above.

The MA Millionaires Tax (and the state-level surtax phenomenon)

Massachusetts enacted a 4% surtax on income above $1 million effective for tax year 2023. New York has a top marginal rate around 10.9% with city add-ons. California's top combined rate exceeds 13%. Several other states have explored or enacted millionaire-bracket surtaxes.

Two engineering complications:

Surtaxes interact with sourcing. The MA surtax applies to MA-source income only — for non-residents, this generally means MA-source wages, capital gains on MA real property, and certain partnership distributions. Engines that apply the surtax to a non-resident's full income produce overstated liability. Engines that apply it correctly require explicit per-item sourcing.

Surtax thresholds shift bracket arithmetic. The MA surtax kicks in at $1M of MA taxable income, which is computed differently from federal AGI. A taxpayer with $950K of federal AGI may have $1.05M of MA taxable income (because Massachusetts disallows certain deductions) and trigger the surtax that the engine, working off federal AGI, would not have flagged.

Surtax-driven planning is now a real category. High-income MA residents are increasingly making domicile-change decisions specifically to avoid the surtax. Your engine's domicile-change ledger needs to handle this case explicitly — a taxpayer who claims a New Hampshire domicile in 2024 but spent 200 days in Massachusetts will lose the audit and owe the surtax retroactively, plus interest and penalties.

Special cases your engine has to handle

The Multi-State Tax Optimization Pack we publish models 320 households across these scenarios — HCOL-to-LCOL relocations, dual residency, MA millionaires tax exposure, NY/CA convenience-of-employer cases, digital nomads with no fixed domicile, equity-compensation residency-change cases, and source-state allocation histories.

Architecture recommendations

A defensible multi-state tax engine has roughly the following architecture:

1. Layer 1
   Day-by-state ledger
   Canonical record of taxpayer location per day. Sources can vary (entry, calendar, payroll feeds), but the ledger is the single source of truth for residency calculations.
2. Layer 2
   Domicile assertion + change ledger
   Per tax year, taxpayer's asserted domicile and the supporting fact pattern. Change events have explicit start and end timestamps.
3. Layer 3
   Income item sourcing
   Each line of income sourced per state, with the sourcing rule version-tracked. Wages, equity comp, capital gains, partnership distributions, K-1 items, retirement income, real-estate income, trust distributions each have their own logic.
4. Layer 4
   Per-state liability calculation
   Per state, per year — taxable income, bracket structure (incl. surtaxes), state-specific deductions and credits.
5. Layer 5
   Resident-state credit reconciliation
   Apply credit-for-taxes-paid mechanisms with the resident state's specific credit cap and limitations on which source-state taxes are creditable.
6. Layer 6
   Audit-defense documentation
   Per layer, produce the supporting record an auditor would request. The engine's job is to make the support automatic.

The most common architectural mistake is conflating Layers 3 and 4 — computing per-state liability without an explicit sourcing layer above it. The result is an engine that can't explain why it computed what it computed, which fails audit-defense.

What we'd test against

Test data exercising each of these patterns is available in our Multi-State Tax Optimization Pack. The pack also covers digital nomads with documented day-count ledgers, dual-residency taxpayers with audit-defensible domicile assertions, and equity-comp residency-change cases.

Closing

The complexity of multi-state tax in a remote-work era has structurally outpaced what tax-software architectures from the pre-2020 world were designed to handle. Engines that worked fine when 95% of taxpayers had a single, obvious state of residence are silently producing wrong answers for the growing population whose facts don't fit that pattern.

The fix is a clean separation of the day-by-state ledger from the domicile assertion from the sourcing logic from the liability calculation from the credit reconciliation. That separation is what allows the engine to explain its outputs in a way that survives audit.

If you're building or rebuilding a multi-state engine and want to compare your test corpus against ours, the free sample on GitHub is the place to start.

Related reading:

• Multi-State Tax Optimization Pack
• Equity Compensation Tax Pack
• QSBS Section 1202 software — a builder's guide
• How to backtest a tax-loss harvesting algorithm with synthetic households

This document is general guidance for engineering teams building tax software. It is not tax or legal advice. State tax law changes annually; engines must be re-validated each tax year.