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.28.0 (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.
State income tax rates 2026
Every jurisdiction's rate schedule from this configuration, and the engine's tax on three wage levels, on one page.
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.
See engine output now, with no key
Your retirement tax in every state computes one household's 2026 state tax
in all 51 jurisdictions, ranked, in your browser, with the engine's JavaScript copy; a gate holds it to the cent to what
POST /api/state-tax/every-state returns. Each state page shows worked examples the engine
computed. These endpoints answer without a key:
GET /api/state-tax/states: the 51 jurisdictions, and how each one is verifiedGET /api/state-tax/rules?state=NJ: one state's rules and sources, as the engine applies themGET /api/state-tax/schema: the request and response formats, as a JSON SchemaGET /api/state-tax/localities?state=OH: one state's local income-tax jurisdictionsGET /api/federal-tax/rules: the federal engine's rulesGET /api/federal-tax/schema: the federal request and response formats
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 | The local income taxes of the engine's locality registry, each jurisdiction named in the request's localities by its official code (GET /api/state-tax/localities?state=XX lists them): City of Wilmington earned income tax (DE); Iowa school district income surtax (IA); Indiana county local income tax (LIT) (IN); Kentucky local occupational license tax (KY); Maryland county / Baltimore City income tax (MD); Michigan city income tax (Uniform City Income Tax Ordinance) (MI); Kansas City and St. Louis earnings tax (MO); New York City resident income tax (NY); Yonkers resident income tax surcharge and nonresident earnings tax (NY); Ohio municipal income tax (OH); Ohio school district income tax (OH); Metro Supportive Housing Services personal income tax (OR); Multnomah County Preschool for All personal income tax (OR); Pennsylvania local earned income tax (Act 32) (PA); Philadelphia Wage/Earnings and Net Profits Tax and School Income Tax (PA). Without localities, IN, MD carry their county tax at the state's average rate unless localTaxRate gives the filer's own. The local taxes outside the registry are listed under what it does not model. |
| 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. |
| Itemized deductions | Partly | A state's itemized deduction, in the states whose page lists it, when the request carries the federal return's Schedule A (computeFederal with federalItemized, on a full-year resident return). |
| Dependents | Modeled | 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). |
| Blindness and disability | Modeled | 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). |
| Refundable credits | Modeled | 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) (engine 1.12.0). |
| Part-year and nonresident returns | Modeled | 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. 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. |
| Tax tables | Modeled | Where a state's instructions make a tax table mandatory (23 states, engine 1.18.0), the tax is looked up as the form does (rules.taxTable). |
What it does not model
- Itemized deductions when the request does not carry the federal return's Schedule A (the return then takes the standard deduction), and the itemized amounts and rules that input does not carry, which each state page lists.
- Credits a state page does not list.
- Dependents: refundable child tax credits and other refundable dependent credits a state page does not list, and dependent credits that need expenses or facts the input does not carry (adoption, custody, certification, a child's schooling); each state page lists its own. Child and dependent care credits, which can apply with no dependent (the care of a spouse who cannot care for themselves), and education credits, which can be for the filer's own schooling, are not part of this item: each state page lists them apart.
- Blindness and disability: 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: 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); and the income of household members outside the return, which is not an input (a program's household income is the return's own).
- 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: 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); 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. For a part-year resident's local taxes: 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.
- Local income taxes outside the engine's locality registry: per-worker head taxes and employer payroll taxes, other Kentucky occupational taxes, Ohio's grandfathered Wyoming and Indian Hill, and a resident's credit for local tax paid elsewhere other than Pennsylvania's Act 32 credit (
otherLocalTaxCredittakes the amount). - 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.
- Optional tax tables (Nebraska's for paper filers only, Connecticut's and Virginia's published only on their websites): the rate schedule is applied to the exact amount instead, which those filers may also use.
- 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.
- Locality registry (JSON): each local income tax the engine calculates, with
its base, form, rules, indexing and official sources;
GET /api/state-tax/localities?state=XXlists one state's jurisdictions with their rates.
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. 304 of the 1368 citations are read from an Internet Archive copy of the official URL, mostly because the state's site refuses connections from the server that runs our automated source check; 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.