State tax docs

State income tax engine documentation

The QuantCalc state tax engine computes a year of state income tax for all 50 states and the District of Columbia. It is one C module with no dependencies beyond the C standard library and libm, it is the same code the retirement planner and the state tax API run, and this documentation is generated from its own configuration. Tax year 2026; engine version 1.14.2 (versioning).

API reference

Every request field, the response, errors, access and examples.

The 51 jurisdictions

Each state's rules as the engine applies them, with sources.

Couples and income types

Per-spouse amounts and the income-type model, with worked examples.

Calculation order

Every step the engine takes, in order, with its code reference and sources.

Verification

How correctness is established, and each state's honest status.

Updates and versioning

The annual cycle, how changes are gated and released, the changelog.

Library and delivery

Running the engine inside your own application.

What the engine models

Area	Status	Detail
Rate schedules	Modeled	Single and MFJ schedules for all 42 taxing jurisdictions; a distinct head-of-household schedule where the state has one (ID, CA, CT, HI, ME, MD, MN, MT, NE, NJ, NM, NY, ND, OK, OR, VT); married filing separately by the state's own rule or by halving the MFJ thresholds.
Standard deductions, exemptions, credits	Modeled	Standard deductions, personal exemptions and their phase-outs, per-exemption and senior credits, and Utah's taxpayer credit, as each state page lists.
Social Security	Modeled	9 statutory treatments; 8 jurisdictions tax some benefits (CO, UT, CT, MN, MT, NM, RI, VT).
Retirement-income exclusions	Modeled	Full exclusions (IL, PA, IA, MS), capped exclusions with age tiers, income limits and Social Security offsets (CO, KY, MI, AL, AR, CT, DE, GA, LA, ME, MD, MO, NJ, NY, OK, RI, SC, VA, WI).
Public vs private pensions	Partly	Separate public-pension treatment where the engine carries it (AZ, MA, AL, HI, KS, LA, MO, NY, WV); elsewhere public pensions follow the general retirement rules. See each state page.
Military retirement pay	Modeled	Its own income type (`pensionMilitary`), with each state's rule applied per retiree at their own age; fully exempt in 28 jurisdictions (plus VT, where the exemption is income-tested).
Wages	Modeled	Its own income type (`wages`): ordinary income everywhere, plus the earned-income rules in GA, OH, WI.
Couples	Modeled	Per-spouse amounts and ages on joint returns: each age-conditioned rule is evaluated per person where the state applies it per person.
Roth conversions	Modeled	Taxed, excluded or drawing the retirement cap, by state.
Capital gains	Modeled	Ordinary treatment, inclusion ratios, flat exclusions, a two-rate schedule (MT), an alternative-rate cap (HI), a surcharge (MD), full exemption (MO) and Washington's excise.
Local income taxes	Partly	County taxes in IN, MD (default average rate, overridable). City and school-district taxes elsewhere are not modeled.
Federal tax deduction	Modeled	AL, MO, OR, when the caller supplies the federal figure.
Surtaxes and recapture	Modeled	California's mental health services tax, the Massachusetts 4% surtax, New York's recapture and Connecticut's add-back and recapture.

What it does not model

Itemized deductions, and credits other than those each state page lists (dependent, earned-income, property-tax, renter, child and similar credits).
Dependents: the dependents input (each dependent's age, and whether a student or disabled) applies every nonrefundable dependent exemption, deduction and credit each state page lists (engine 1.7.0), and counts the qualifying children of the earned income credits (engine 1.12.0). Not calculated: refundable child tax credits and other refundable credits a state page does not list, credits that need expenses (child and dependent care, education) and facts the input does not carry (adoption, custody, certification); each state page lists its own.
Blindness and disability: the blind and disabled inputs (per person) apply every blind amount and every disability route to a state's age-based relief that each state page lists, and the disability pay input applies the disability-income exclusions (engine 1.7.0). Not calculated: low-income or wage-tested disability credits and rules that need facts the inputs do not carry; each state page names its own.
Refundable credits (engine 1.12.0): the earned income credits, and the property-tax, renter's, grocery and senior credits each state page lists, are calculated into refundableCredits and netTax (tax stays the liability before them) from the facts given (propertyTaxPaid, rentPaid, rentIncludesHeat, homeValue, taxExemptInterest, medicalExpenses; a fact not given is none, and inputsNotSupplied says when giving one would change the result). A program's household income is the return's own: income of household members outside the return is not an input. Not calculated: programs claimed on their own application or claim form rather than with the return's credits (New Jersey's ANCHOR, Senior Freeze and Stay NJ, Pennsylvania's Property Tax/Rent Rebate, Minnesota's homeowner Homestead Credit Refund, Vermont's property tax credit, Kansas's homestead and senior property tax refunds, Maryland's homeowners' and renters' tax credits, Colorado's property tax/rent/heat rebate, Utah's circuit breaker, Arizona's property tax credit, Michigan's home heating credit), and each program's rules for property that is not the filer's main home all year (part-year ownership, shared or business use, mobile-home lots, nursing homes).
Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.
Part-year and nonresident returns (engine 1.12.0, residency) are calculated for every taxing state by its own method, and (engine 1.13.0, residency.spouse) a married couple whose residency differs by the state's own rule for the pair, every treatment it allows computed; the pairs a state's instructions do not address, and the joint or separate returns whose computation is the state's own, are listed on its page and refused. Not calculated: a nonresident servicemember's military pay, nonresident aliens, installment-sale elections, reciprocity agreements between states (the caller leaves the wages a reciprocal agreement exempts out of stateIncome), the earned income and low-income credits on these returns, the dependent credits (dependents are refused with residency), Virginia's Filing Status 4 on the 760PY, Hawaii's joint-return election taxing the combined income for the part-year resident's period, the credit for tax paid to the other state on a joint resident return, and a couple's local returns (localities are refused with residency.spouse). Local taxes with residency (engine 1.13.0) are calculated for a part-year resident of New York City and Yonkers (Form IT-360.1), a Pennsylvania EIT subdivision (the Local Worksheet), an Ohio earned-income-base school district (SD 100), for a county or Iowa school district on a part-year return and for a nonresident's workplace; not calculated: a part-year New York City resident's NYC school tax credits and NYC earned income credit, and the part-year rules of Philadelphia, Ohio municipalities and traditional-base school districts, Michigan cities (Detroit Form 5120), Kentucky, Kansas City, St. Louis, Wilmington, Portland Metro and Multnomah County, a part-year Yonkers resident's nonresident earnings tax, an Indiana nonresident's county tax and Maryland's Form 515: the API refuses the inputs these need.
State alternative minimum taxes.
City, school-district and other municipal income taxes outside the engine's locality registry (engine 1.12.0 calculates the jurisdictions of research/data/state-tax-localities.json named in localities: NYC, Yonkers, the Maryland and Indiana counties, Iowa school districts, Ohio school districts and municipalities, Pennsylvania earned income taxes and Philadelphia, Michigan cities, Louisville and Lexington, Kansas City and St. Louis, Metro and Multnomah County, Wilmington): per-worker head taxes and employer payroll taxes, other Kentucky occupational taxes, Ohio's grandfathered Wyoming and Indian Hill, and resident credits for local tax paid elsewhere (otherLocalTaxCredit takes the amount; Pennsylvania's Act 32 credit is computed). Without localities, Indiana and Maryland use the average county rate.
Business income rules: pass-through entity taxes, net operating losses, depreciation differences and other state additions and subtractions outside the income types listed on the API reference.
Tax-table lookups: where a state's instructions have filers look tax up in a table of income bands, the engine applies the rate schedule to the exact amount.
Withholding, estimated payments, penalties and interest: the engine computes the year's liability only.
Out-year rules that are not yet law: later years reuse this year's rules with indexed dollar amounts (see Later years).

Each state page lists what the engine does not calculate for that state; the calculation order page walks every step the engine does take.

Data you can download

Engine configuration (JSON): every configuration field for every jurisdiction, the bracket tables, the rules the engine holds as code, and the worked-example results. Produced by the engine's own dump tool.
Provenance (JSON): for every state and rule, the source URLs, what each source establishes, the exact wording checked on the source, and the date it was checked.
Verification status (JSON): each state's audit class and known approximations.

How sources are kept current

Each source in the provenance file carries the figure or phrase it is cited for, exactly as the source prints it. A weekly job fetches every source (HTML and PDF), confirms that wording is still there, flags dead links and pages that now redirect elsewhere, and updates the checked dates shown on these pages. 266 of the 1260 citations are read from an Internet Archive copy of the official URL, mostly because the state's site refuses connections from the checker; the page links the copy that was read. A build gate fails when a rule on a state page has neither a source nor a stated reason why none could be confirmed, when a source has no checked date, or when the engine's value no longer matches the value a source was checked against. 3 rules currently carry only such a reason; they are listed on the verification page. Details are on the verification page.