State tax docs / Calculation order
How the state tax engine computes a year of tax
Every step the engine takes, in the order it takes them, from the API request to the final tax. Each step names the code that performs it, the configuration and inputs it reads, the jurisdictions it applies to, and where its sources are. The state pages walk the same steps for one jurisdiction with its own figures (States). Engine version 1.14.2, tax year 2026.
This page is generated from the engine's calculation registry (research/data/state-tax-calc-registry.json). A build gate reads the engine
source and fails when a function, a marked step, a configuration field or an input the engine reads is not in the registry, when a step has
no source or is missing from this page or a state page, or when a line reference here is out of date.
The pipeline in brief
- Parse and check the request; map it onto the engine input (request handling).
- Pick the jurisdiction, the filing status's rate schedule and deduction (configuration).
- Form the income total the income tests use, nest the income subsets, attribute income to each spouse (income).
- Take out what the state excludes: military pay, public and employer pensions, Social Security, retirement income, conversions, gains (exclusions).
- Subtract the standard deduction, exemptions and age subtractions, and any federal-tax deduction (deductions, taxable income).
- Apply the rate schedule and the state's recapture, gains rates and minimum tax (tax).
- Subtract nonrefundable credits, floored at zero (credits).
- Add the county tax, capital-gains surcharge and surtax (after credits).
Request handling (API and library entry point)
Three stages: parse, evaluate, respond
The JSON body is parsed (type checks only), then evaluated (value checks, mapping onto the engine input, the engine call), then turned into the response. A typed caller can enter at the second stage with the same checks. A body that is not JSON returns 400 before any of this.
State code
state (or state_code) must be a non-empty string. A code longer than seven characters is read as unknown. The lookup is case-insensitive.
The request field table
Every request key is one row of a table: its camelCase name, the snake_case spelling also accepted, its type, where it may appear (top level, spouse, dependent), its limits, and for amounts where it lands. The parser reads the amounts, the limits and the keys a spouse or dependent object may carry from these rows, and GET /api/state-tax/schema is generated from them, so the published JSON Schema is what the parser accepts. Every key of more than one word also has a snake_case spelling (survivorBenefits, socialSecurityDisability and priorHohQualifyingPersonDied gained theirs 2026-09-28). A row also names the presence word its bit is kept in (the request records which optional keys were given; the fields added in the final 1.8.0 round have their own word).
Filing status
filingStatus (or filing_status): absent or null means single; otherwise one of nine case-insensitive strings (single, mfj or married_filing_jointly, mfs or married_filing_separately, hoh or head_of_household, qss or qualifying_surviving_spouse). A non-string or any other value is refused with 400. The response echoes the status as single, mfj, mfs, hoh or qss. A qualifying surviving spouse is one person on the return (no spouse object).
The four original fields
ordinaryIncome, socialSecurity and capitalGains are optional numbers and age an optional whole number: absent or null means 0 (not given). Since engine 1.5.0 a value of the wrong type, or an age that is not a whole number, is refused with 400 naming the field, like the newer fields (the first release read a wrong type as 0 and truncated the age); an age outside 0 to 120 keeps its original message.
Optional amounts added in 1.1.0
wages, selfEmploymentIncome, iraDistributions, employerPlanDistributions, pensionPrivate, pensionPublic, pensionMilitary, rothConversion, shortTermGains, qualifiedDividends, railroadRetirementTier2, railroadRetirementTier1, socialSecurityGross, federalTax, federalNiit, federalTaxBeforeCredits, federalRefundableCredits and localTaxRate: absent or null means not supplied; anything but a number is refused with 400 naming the field. Snake-case spellings are accepted.
Social Security coverage of a public pension
pensionPublicSsCovered must be true or false; absent or null means unknown. Only false reaches the engine (as pension_public_not_ss_covered = 1).
Blindness and disability
blind and disabled (and spouse.blind, spouse.disabled) must be true or false; absent or null means false. They reach the engine per person: the top-level pair is the primary filer, the spouse pair the spouse on a joint return.
Dependents
dependents is an array (absent or null: not said, which means none; an empty array: none) of at most 20 objects, each with a required whole-number age (at the end of the year, from 0 to 120) and optional student and disabled flags; any other key, type or value is a 400 naming the element. They reach the engine as the household's dependents; a head of household lists the qualifying person here when that person is a dependent.
Person facts
earlyDistributionException (none, sepp, death, disability or other), survivorBenefits, socialSecurityDisability and priorHohQualifyingPersonDied are typed like the other flags (a wrong type or value is a 400 naming the field; absent or null: not said). The amounts pensionFederalCivilService, disabilityIncome, earlyDistributions and iraBasis are checked like the other amounts; earlyDistributions may not exceed iraDistributions plus employerPlanDistributions. The spouse object carries the spouse's own values of each, plus socialSecurityGross (the spouse's part of the household figure, which must be given and at least as large). The plan age, the deceased spouse's age and survivor Social Security are the next step. On a married-filing-separately return spouse may carry only the other spouse's age and blind.
Plan age, deceased spouse's age, survivor Social Security
planMinimumRetirementAge and deceasedSpouseAge are whole numbers from 1 to 120 and socialSecuritySurvivor is true or false, at the top level (the primary filer's, or the household's without spouse) and in spouse (joint returns); a wrong type or value is a 400 naming the field, absent or null means not said (each state's earlier reading). They reach the engine as the person's plan minimum retirement age (CT line 48b, ME, OH line 42), the deceased spouse's age (SC line p-3) and the survivor-benefit fact of the person's Social Security (CO under 55), and are echoed in input when given.
The facts a person field needs
planMinimumRetirementAge describes the plan paying the person's disabilityIncome, so it needs disabilityIncome at the same level; deceasedSpouseAge describes a surviving spouse's income, so it needs survivorBenefits: true at the same level. Otherwise a 400 names the field. On a married-filing-separately return spouse may not carry any of the three.
includeSources
includeSources (boolean, default true) shapes the response only: false leaves rules.sources and rules.unsourced out; the tax and every other field are identical. A non-boolean is a 400 naming the field. includeInputsNotSupplied (boolean, default true, engine 1.10.0) likewise: false leaves inputsNotSupplied out and runs none of its probes. includeNotModelled (boolean, default true, engine 1.12.0) likewise: false leaves notModelled out.
strict
strict: true makes stage 1 refuse the top-level keys the API does not read, naming up to five of them, before any other check; keys match as the API matches them (any case, either spelling, and the keys the computeFederal path reads). Absent, null or false: unknown top-level keys are ignored, as always. A non-boolean is a 400 naming the field.
projection (types)
projection is absent/null (none) or an object with exactly the keys year (required, a whole number), inflation and cpiFactor (one of the two, a number); any other key, type or combination is a 400 naming it. The values are checked in stage 2.
projection (values)
The projection's year must be the rules year up to the last projectable year, inflation within its range (the factor is then (1 + inflation) to the power of the years after the rules year), or cpiFactor within its range and 1 for the rules year itself; then the configuration is projected (the indexing step) and kept beside the rules year's for the response.
Does an amount bear on this result?
A registry amount bears on a request when setting it to zero, or far above its value (a bracket table's thresholds to zero or ten times, an age test to 0 or 200), changes the tax the engine computes for the same input. A table held in code has no field to vary and does not.
Refusing an unsettled projection
With a projection past the rules year, a request whose result depends on an amount the registry marks not established (no official source settles how it moves) is refused with a 400 naming the state and the amount, rather than priced on a guess.
The projection in the response
A projected response carries projected: true, rulesYear and projectedYear, and a projection block: the factor, every amount that bears on the result with its rules-year and projected values, rule, method and multiplier (and the value year, the scheduled year or the age shift where they apply), the state's tables held in code, the rules those amounts belong to with their statements and sources (sources omitted with includeSources: false), what the projection does not apply, and the changes the state enacted for later years that it does not apply. With indexing "inflation" it says so (indexing, the first notApplied line), gives each amount the method that mode applied (inflation, held, birth_year) and the law's (lawMethod), and adds each enacted schedule to enactedChangesNotApplied. Engine 1.12.1: with localities, each local amount that bears on the result (local.<code>.<amount>) with the way its law moves it, the locality's rate schedules and credit tables as code tables, and one rule per local tax (local.<kind>), with settledUntil where the law stops settling it.
What the request did not supply
inputsNotSupplied: for each fact or split the API accepts that the request did not give and that could apply to it (age, the spouse's age or the per-spouse split, blindness, disability, dependents for a head of household, the public-pension coverage fact, the pension and plan types, early distributions and their exception, IRA basis, survivor facts, the gross or taxable Social Security, qualified dividends, a loss carryover, the federal figures, the county rate, the head-of-household fact), the request is evaluated again with each of a fixed set of probe values (the projection included; with computeFederal the federal engine too), and the input is listed when a probe changes the tax, with its rule family, what was assumed, what was probed, and the lowest and highest tax over the probes and the result as given. includeInputsNotSupplied: false leaves it out and runs no probes.
What the state's law has that the engine does not model
notModelled (engine 1.12.0): every item of the state's not-modelled list — generated by scripts/gen_state_tax_not_modelled.mjs from the state's form-map lines the engine does not model and the state's not-calculated list, each with its official source — and whether it can bear on this request (couldApply: true, false or unknown, with the reason; part-year items follow residency, dependent-care items a dependents list of [], payments are false, tax-table differences true, everything else unknown).
Spouse object
spouse must be an object whose keys are only the spouse's own amounts and facts: age, wages, iraDistributions, employerPlanDistributions, pensionPrivate, pensionPublic, pensionMilitary, rothConversion, pensionFederalCivilService, disabilityIncome, earlyDistributions, earlyDistributionException, iraBasis, survivorBenefits, socialSecurityDisability, socialSecurityGross, railroadRetirementTier2, railroadRetirementTier1, selfEmploymentIncome, blind and disabled (or their snake-case forms). spouse.age must be a whole number from 1 to 120.
Value checks
In this order: state present, state known, the three original amounts not negative, finite and at most $100,000,000,000, age 0 to 120, every other amount finite, not negative and at most $100,000,000,000, socialSecurityGross at least socialSecurity when both are given, spouse only with mfj (or mfs for the age and blindness), spouse.age 1 to 120, then the spouse's amounts, the early parts, the Railroad Retirement Tier 1 parts and localTaxRate. The first failure is returned.
Amount limits
Each amount added in 1.1.0 must be finite, not negative, and at most $100,000,000,000.
Self-employment income needs the federal return
selfEmploymentIncome (and spouse.selfEmploymentIncome) is a business's net profit. The state's earned income from it is the profit less the deduction for half the person's self-employment tax (federal Schedule 1 lines 3 and 15), which only the federal return computes, so an amount other than 0 is refused with 400 unless computeFederal is true. With it, the federal engine prices each person's Schedule C and Schedule SE, and each person's profit less half their self-employment tax is added to their wages as the state's earned income.
Mapping the request onto the engine input
Other ordinary income = ordinaryIncome + wages (with computeFederal, plus each person's self-employment profit less half their self-employment tax) + shortTermGains + qualifiedDividends; the part that is not wages or short-term gains is flagged as investment income (interest and dividends) for the states that pool it. Retirement distributions = IRA + employer-plan distributions + private pension + public pension + military pay. Pension income = private + public pension. Tier 2 railroad benefits and the Tier 1 part of the gross benefits are passed apart. With a spouse object the person amounts are summed for the household and the spouse's own share is passed as the split. federalTax and federalNiit are unknown (no deduction) when absent. The federal-taxable-income inputs are always unknown on the API. An absent spouse.age means the primary filer's age. A qualifying surviving spouse is passed as single with the status flag.
Effective rate
effectiveRate = tax divided by the sum of every income amount supplied (both spouses' amounts included); 0 when that sum is 0.
Response document
The response carries the state, the tax, the effective rate, the input as read, the rules block, the breakdown, a note, the state's documentation link, the tax year and the engine version.
The rules block
rules reports the state's parameters for the request: Social Security rule, bracket count, standard deduction, personal exemption, senior subtraction, capital-gains treatment, the retirement exclusion, the military and wage rules and the local tax. Since engine 1.5.0 the scalar amounts are the ones the engine uses for the request's filing status (a head-of-household or separate schedule, deduction, exemption or exclusion cap where the state has one; an income-tiered exemption at the request's income total), before age additions, phase-outs and credits.
The sources in the response
rules.sources carries, for each rule family that bears on the request, the family's official sources as the provenance research records them: url, title, kind, whether the kind is official, the first verified quote and the date it was checked. The data is generated from research/data/state-tax-provenance.json into backend/src/state_tax_provenance_data.h (scripts/gen_state_tax_embedded.mjs; a gate fails when it is stale), so the API and the library cite the same sources. The rate schedule, deductions, local tax, federal interaction, surtaxes and no-income-tax rule always bear on a return; the others when the request carries what they read: Social Security with socialSecurity or socialSecurityGross, retirement income with any retirement money or Tier 2 annuity, public pensions with pensionPublic or a civil service annuity, military retirement with pensionMilitary, wages with wages, conversions with rothConversion, capital gains with either gain or qualified dividends, the age rules with an age, blindness and disability with any of those facts, disability pay, Social Security disability or a disabled dependent. rules.unsourced names each of those families that has no official source, with the reason.
Amounts for the filing status
The schedule the filing status uses (its bracket count), its own standard deduction (head of household, separate), its personal exemption (head-of-household amount, or the income tier for the request), the senior subtraction and the retirement exclusion cap (the separate cap where the state sets one), as the calculation selects them.
The breakdown and perPerson blocks
breakdown is the engine's detail record summed over the household; perPerson (with a spouse object) is one entry per person, from the same record.
Error body
Every 400 has the body {"error": "<message>"}; the messages are listed verbatim on the API reference.
Railroad Retirement Tier 1 checks
railroadRetirementTier1 is the Tier 1 part of socialSecurityGross, so it needs socialSecurityGross and may not exceed it. spouse.railroadRetirementTier1 is the spouse's part of the household figure: it needs railroadRetirementTier1 and may not exceed it, nor (when spouse.socialSecurityGross is given) the spouse's own gross, with the primary filer's rest within the primary's own gross. Comparisons of sums and differences allow for binary rounding of amounts in cents.
County rate (localTaxRate)
localTaxRate (a fraction of one, not a percentage) applies only where the engine includes a county income tax (Indiana and Maryland), and must lie between the lowest and highest official county rate of that state; it then replaces the population-weighted average. Elsewhere, or out of range, the request is refused with 400.
Limits on the original amounts
Since engine 1.8.0 ordinaryIncome, socialSecurity and capitalGains get the same checks as every newer amount: finite and at most $100,000,000,000 (a JSON number too large for a double, such as 1e999, is refused instead of priced).
prior-year figures (response)
Every response lists, in priorYearFigures, each indexing-registry parameter whose value is a prior-year (2025) figure because the state has not published the 2026 one, when that parameter bears on this result (setting it to 0 or far higher changes the tax): parameter, rule, valueYear, value, why. An empty list means every amount the result used is a 2026 figure.
localities (types)
localities is absent/null or an array of at most 6 entries, each a code string or {code, role, wages}; any other shape or key is a 400 naming it.
localities (values)
Each code must be a modelled jurisdiction of the request's state; one residence per kind; a workplace only for earned-income taxes, with wages at most the household's; localTaxRate excludes a county code; otherLocalTaxCredit needs a residence filing a separate return and localUnearnedIncome a Philadelphia residence. A county code then sets the county rate.
Local taxes with residency (values)
Engine 1.13.0: a resident locality's own period (residentFrom / residentTo, inside a part-year return's period) and residentIncome; a county or Iowa school district follows one day (MD the last day of Maryland residence, Iowa the last day of the year, Indiana January 1) and is refused on a nonresident return (MD's special nonresident tax, IN Section 2, no Iowa district); a nonresident lives in no locality (a workplace is role work); the localities without a settled part-year rule are refused with the reason. A part-year resident's input: the period's income (the spouse split in the year's proportions) and a resident's state return on it (NYC: the Proration chart's deduction and dependent exemptions). Engine 1.14.0: Philadelphia (not with net profits), Ohio municipalities and traditional-base districts (the period alone), Lexington, Kansas City / St. Louis (daysOutside, workDays; not with net profits; a joint request only with one spouse's wages), Metro, Multnomah, Detroit (whole months) and Grand Rapids (neither beside a workplace of the same city) are computed; Louisville, Wilmington and the other Michigan cities stay refused with the reason.
Local taxes in the result
tax adds NYC, Yonkers and an Iowa school district (lines of the state return); totalTax adds the separate local returns.
Local taxes on a part-year or nonresident return only when the caller gives a part-year or nonresident residency
The county (MD, IN) is in the part-year return's tax; an Iowa school district's surtax is on its tax after the IA 126 credit; NYC and Yonkers part-year lines join tax; the separate local returns (and a workplace's) join totalTax.
local (response)
The local block: the lines on the state return (with the average-rate county tax of Indiana and Maryland when no county is named) and the separate returns, each with its base, rate, gross tax, credits and tax.
localities not supplied
Where the state has local income taxes beyond a county and no localities were given, inputsNotSupplied probes the highest-rate jurisdiction of each kind of residence, on tax and totalTax; a Philadelphia residence without localUnearnedIncome is probed with the ordinary income other than wages plus the short-term gains.
credit facts not supplied
Without propertyTaxPaid or rentPaid, inputsNotSupplied probes a property tax and a rent (two amounts each) on tax, totalTax and netTax; with a rent but no rentIncludesHeat, heat included; with a property tax but no homeValue, a home value over every credit's limit. taxExemptInterest and medicalExpenses are amounts (absent means none).
Credit facts
propertyTaxPaid, rentPaid, homeValue, taxExemptInterest and medicalExpenses are amounts; rentIncludesHeat a boolean that needs rentPaid.
refundableCredits and netTax
The refundable credits, before the local taxes (the Yonkers surcharge's base is the state tax less the NYS EIC, the real property tax credit and the NYC school tax credits); netTax = totalTax less them.
Homestead credit or retirement income subtraction (WI)
Wisconsin does not allow the homestead credit with the 67+ retirement income subtraction; with a homestead credit in reach and the subtraction lowering the tax, the return is also computed without the subtraction and the one that leaves less to pay is kept.
residency (types) only when the caller gives a part-year or nonresident residency
residency is absent/null or an object {status (resident, partYear, nonresident), residentFrom, residentTo (YYYY-MM-DD in the tax year), stateIncome {amounts}}; any other shape or key is a 400 naming it.
residency (values) only when the caller gives a part-year or nonresident residency
A part-year return needs its resident period, in order; each stateIncome amount is at most the year's amount; a nonresident's retirement income and Social Security are refused; dependents, localTaxRate, the credit facts and the military / civil service / disability / employer-plan / self-employment / railroad / qualified-dividend amounts and person facts are refused with residency (engine 1.13.0: a spouse split is taken with residency.spouse, localities with stj_local_py; a couple's localities are refused); Washington's excise is refused. The state-source input is the household with stateIncome's amounts.
residency.couple in the response only when the caller gives a part-year or nonresident residency
The pair, the state's rule, every option (computed: tax, totalTax, netTax and each return's residency, method, form, tax and ratio; not computed: why), the applied one and why, the lowest, and which return the breakdown describes.
Which treatment is tax only when the caller gives a part-year or nonresident residency
The state's only treatment, else its default absent an election, else residency.election, else (a free choice) the joint return the request's mfj names, or the next the state allows when that one is not computed; never silently the lowest: residency.couple names the applied one, why, and the lowest computed (null when shared). The applied one not computed is a 400 with its reason.
A couple's joint resident return only when the caller gives a part-year or nonresident residency
The request without residency: both spouses taxed as full-year residents on the whole year's joint income (the credit for tax paid to the other state is not computed).
Couple rules that turn on the couple's facts only when the caller gives a part-year or nonresident residency
Engine 1.14.0: Massachusetts RP / RN (G.L. c. 62C 6(a)(2) and 830 CMR 62.5A.1(11)(a): separate returns when a spouse has no filing requirement, or, RN, the nonresident has income unrelated to Massachusetts and the couple's Massachusetts income is at most the c. 62, 4(d) threshold; decided only where the amounts settle it), Vermont RN (TB-55: a nonresident spouse without Vermont income: a joint return as residents or the resident's recomputed separate return; with Vermont income: the joint IN-113 return only), Virginia NN1 (Form 763 Filing Status 3 when the other spouse has no income from any source, else Filing Status 4, separate). The condition applied is residency.couple.condition.
A couple's separate returns only when the caller gives a part-year or nonresident residency
Each spouse's own married-filing-separately request (their own amounts, the other's age and blindness as the mfs spouse facts): a resident return, or their own part-year / nonresident return; a nonresident with no income from the state files none. Engine 1.14.0: Maine's Schedule NRH returns are single returns on each spouse's own share ("Filing Status: Check Single"), the nonresident credit by line 7 Column C. Not computed with the joint return's federal amounts (the as-if separate federal returns are not inputs), where the state's separate computation is not settled (Utah's Special Instructions: no base phase-out amount for filing status 9) or conditional (California: only with a nonresident spouse who had no California income; Massachusetts: stj_couple_conditions).
Per-spouse proration on a joint return only when the caller gives a part-year or nonresident residency
Where the form prorates per spouse: VA 760PY each spouse's exemptions and age amounts by their own Ratio Schedule (days / 365, three places; a full-year resident 1); MI Worksheet 6 the full-year resident's exemption allowance in full, the other's by their own Michigan income over their own total income; MO-NRI each spouse's own Missouri income percentage on the tax of their own share of taxable income (MO-1040 lines 27-33); MD Worksheet 13A the pension exclusion by each spouse's own months of residence.
A couple's joint part-year / nonresident return only when the caller gives a part-year or nonresident residency
The state's own method (state_tax_residency_tax) on the couple's state amounts: a full-year resident spouse's whole income, the other spouse's stateIncome, each spouse's part kept for the per-person rules; the period from the earliest to the latest day either lived in the state. Indiana's county tax per spouse by January 1 (Schedule CT-40PNR) is refused when only one spouse lived in Indiana then.
The state's rule for a couple whose residency differs only when the caller gives a part-year or nonresident residency
Engine 1.13.0: for each taxing state and pair, the treatments its instructions allow (a joint part-year / nonresident return, separate returns, a joint resident return), the one that applies absent an election, the joint return's residency and form, and the joint or separate returns the engine does not model (each with its reason): g_couple_rules, every row quoted from the state's 2025 instructions.
A couple whose residency differs (values) only when the caller gives a part-year or nonresident residency
Engine 1.13.0: with residency.spouse the request is a joint one with the spouse object; each spouse's own amounts (the person amounts, and the household amounts split by spouseShare, each needed when not 0) bound that spouse's stateIncome; a nonresident spouse's retirement income and Social Security are refused (4 U.S.C. §114); the pair is classified (RP, RN, PN, PP, NN1, or the same residency) and the state's rule for it decides the treatments.
residency.spouse, spouseShare, election (types) only when the caller gives a part-year or nonresident residency
Engine 1.13.0: residency.spouse is absent/null or an object {status, residentFrom, residentTo, stateIncome} (the spouse's own); residency.spouseShare an object of the spouse's parts of the household amounts; residency.election joint, separate or jointAsResidents; any other shape or key is a 400 naming it.
residency (response) only when the caller gives a part-year or nonresident residency
The response's residency block: status, method, form, the full-year tax, the ratio's numerator, denominator, value and places, the proration and its basis (income, days, months), MD's special nonresident tax, and what is not modelled.
Configuration, filing status and entry points
Each jurisdiction's configuration
On first use the engine fills one configuration record per jurisdiction (rate schedules, deductions, exclusions, flags), each value cited beside it in the source. The record is read-only afterwards; every calculation reads from it.
Military and wage rules
Military retirement and earned-income rules are set per jurisdiction in a second pass over the same records.
Blindness, disability and the 1.5.0 additions
A third pass over the same records sets the engine 1.5.0 rules: blind amounts, disability routes, head-of-household amounts and the personal and senior credits the blind-and-disability survey found, each cited beside it.
The 1.6.0 group-1 additions
A fourth pass sets the engine 1.6.0 rules the worksheet replays of Arizona, Arkansas, California, Georgia, Hawaii, Iowa, Idaho and Illinois found: Arkansas's 65 Special credit, Low Income Tax Tables and qualified-individual credit; Georgia's short-term gains in the retirement pool and low income credit; Hawaii's statutory floor under the alternative gains tax; Iowa's low-income exemption, single tax reduction and alternate tax; Idaho's separate-return and employed-retiree rules and Permanent Building Fund tax; Illinois's exemption cut-off at high federal AGI. Each is cited beside it.
The 1.7.0 additions (household facts)
A fifth pass sets the engine 1.7.0 rules that read the household facts the API gained: the dependent exemptions, deductions and credits of every state that has them, the family-size and household credits, the federal civil service annuity deduction, the disability-pay exclusions, the early-distribution rules, the Social Security disability rule, the pooled separate-return exemptions, and the retiree credits surveyed with them. Each is cited beside it.
The 1.8.0 additions (ME MI MN MO MS ND NE)
A sixth pass sets the engine 1.8.0 rules for Maine, Michigan, Minnesota, Missouri, Mississippi, North Dakota and Nebraska that the hardening review found and that need no new input: Maine's phase-outs on Maine AGI, its separate-return pension range and disability pay; Michigan's Tier 2 add-on; the Minnesota and North Dakota marriage credits and Minnesota's past-military-service credit; Missouri's per-spouse tax, federal tax deduction, head-of-household exemption and Missouri-AGI income tests; Mississippi's pensions at any age; Nebraska's federal tax cap, separate-return age amount and CSRS exclusion. Each is cited beside it.
The 1.8.0 S2 additions
A sixth pass sets the engine 1.8.0 rules for Delaware, Georgia, Illinois, Kentucky, Louisiana, Massachusetts and Maryland found by the form-line hardening audit: the investment income in the Delaware and Georgia retirement pools, Delaware's combined separate return, Illinois disability pay, Kentucky's separate-return deduction and 2026 family size table, Louisiana's no-federal-return rule, the Massachusetts excess-exemption order, and Maryland's earned income, poverty level and age-100 rules. Each is cited beside it.
The 1.8.0 (S5) additions
A sixth pass sets the Virginia, Wisconsin and West Virginia rules the 2026-09-27 hardening review found missing: Virginia's Spouse Tax Adjustment, its no-tax threshold and the choice between the age deduction and the disability subtraction; Wisconsin's standard-deduction phase-out at Wisconsin income and its low-income retirement income subtraction; West Virginia's per-person senior modification. Each is cited beside it.
The 1.6.0 worksheet rules (group 2)
A fourth pass sets the engine 1.6.0 rules the worksheet replays of Indiana, Kansas, Massachusetts, Maryland, Michigan, Minnesota, Mississippi and North Carolina found: the Massachusetts wage deduction, short-term gain rate and low-income relief, the Maryland Senior Tax Credit and two-income subtraction, the Michigan Standard Deduction, the Minnesota age-65 and alternate Social Security subtractions and deduction limitation, and the Mississippi head-of-family exemption, each cited beside it.
Worksheet findings for NM, OH, OR, PA, RI, SC, UT and VT (1.6.0)
A further pass over the same records sets the engine 1.6.0 rules the group-3 worksheet replays found: New Mexico's separate-return gains deduction, Ohio's MAGI tests and credits, Pennsylvania's tax forgiveness, Rhode Island's deduction and exemption phase-out, South Carolina's two wage earner credit, Utah's credits and Vermont's gains cap, each cited beside it.
The 1.8.0 additions (S4: NJ NM NY OH OK OR SC)
A pass sets the engine 1.8.0 rules found by the hardening review of New Jersey, New Mexico, New York, Ohio, Oklahoma, Oregon and South Carolina: New Jersey's no-tax filing threshold, veteran exemption, disability-pension and line 27 rules; New Mexico's centenarian exemption; New York's married-filing-separately schedule; Ohio's survivor-benefit deduction and the end of its disability deduction at 65; Oklahoma's prorated child credit; Oregon's severe-disability credit for a blind person; South Carolina's surviving-spouse deductions. Each is cited beside it.
The 1.8.0 S1 additions (AL AR CA CO CT DC)
A pass sets the engine 1.8.0 rules for six states' hardening findings that need no new input: Alabama's standard deduction chart and dependent chart on Alabama AGI, Arkansas's high-income table, capital gain cap, filing status 4 and two early-distribution corrections, California's senior head-of-household income test after the military exclusion, Colorado's one subtraction for a young survivor's military pay, Connecticut's personal tax credit table, Social Security worksheet Line B and strict threshold, disability pay outside the pension subtraction, and the District of Columbia's survivor annuity exclusion and disabled exclusion tests. Each is cited beside it.
Looking up a jurisdiction
A two-letter code (case-insensitive) or NONE selects a configuration. Initialisation runs once, thread-safely. NONE has no brackets, so its tax is always 0.
Entry points
compute_state_tax_detail() is the calculation (it weighs the elections below, each a run of the same computation); compute_state_tax_v4() calls it without a detail record. The older v3, v2 and compute_state_tax() pass the documented unknowns: no public-pension or pension split, no federal tax (so no Alabama or Oregon deduction) and no federal taxable income (so the component model).
Past-military-service credit or the military subtraction
Where the state's credit for past military service is claimed instead of the military subtraction, a return with military pay is computed both ways — with the subtraction (no credit) and with the pay taxed and the credit — and the lower tax is the one returned, with its trace.
Combined separate return (two columns on one form) joint returns with each spouse's own amounts given
A joint return that gives the spouse's own amounts is also computed as two separate returns on one form: each spouse's own income (the items with no owner, such as interest, gains and Social Security, half each) at that spouse's age and facts, the per-dependent credits divided between the columns the cheapest way. The lower of that and the joint return is the tax; the joint return's lines stay in the breakdown.
Per-person mode joint returns with the spouse's age given
On a joint return with the spouse's age given, every age test the state applies per taxpayer is evaluated for each spouse at their own age. Without it one household age applies to both.
Blindness and disability, per person only when the caller says a person is blind or disabled
The filer is person one; the spouse counts only on a joint return and only when the caller says so (there is no household convention as for age). Where a state lets a disabled person (and, where it says so, a blind one, or one whose spouse is disabled) qualify for its general retirement exclusion before the age, that person is treated as having reached the age for that exclusion only. Of the 42 taxing jurisdictions, these have a blind amount: Arizona, Arkansas, California, Colorado, Delaware, the District of Columbia, Hawaii, Idaho, Illinois, Indiana, Iowa, Kansas, Kentucky, Maine, Maryland, Massachusetts, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, New Jersey, New Mexico, North Dakota, Oklahoma, Oregon, Utah, Vermont and Virginia; these have none: Alabama, Connecticut, Georgia, Louisiana, New York, North Carolina, Ohio, Pennsylvania, Rhode Island, South Carolina, West Virginia and Wisconsin. A disability route is calculated in Arkansas, the District of Columbia, Georgia, Hawaii, Idaho, Iowa, Maryland, Michigan, New Jersey, Oregon and West Virginia.
The dependents counted only when the caller lists dependents
The caller's dependents list (none when not said). Each dependent's age, student and disabled facts are read by the rules below that condition on them.
Rate schedule and standard deduction by filing status
Single uses the single schedule and deduction; married filing jointly the joint ones. Head of household and married filing separately follow the two steps below.
Married filing separately
Where the state publishes its own separate schedule, that one (with half the joint deduction unless a separate deduction is set). Where one schedule applies to every status, that schedule unscaled with the single deduction. Otherwise the joint schedule with every threshold and the deduction halved (computed as the joint tax on twice the income, halved).
Head of household
The state's head-of-household schedule where it has one, else the single schedule; the head-of-household deduction where set, else the single deduction.
A separate deduction for married filing separately married filing separately
Where set, this amount replaces the deduction the schedule rule above gives married filing separately.
No broad income tax
A jurisdiction with no brackets returns 0 at once, except Washington's capital-gains excise below. Military pay is still attributed per person in the detail record.
Washington capital-gains excise
The excise rate on long-term gain above the excise deduction, plus the additional rate on gain above the high threshold. Nothing else is taxed.
No tax without a federal return
When the household's federal gross income (the income total, Social Security only in its taxable part) is under the federal filing threshold for the status (the basic standard deduction plus the aged amount per person 65 or older; a fixed amount on a separate return), the state tax is zero.
Federal filing threshold
The federal gross-income filing threshold for the status: the state's (federal) standard deduction plus the 65+ amount per person 65 or older; a fixed amount for married filing separately.
The filing status’s own amount
Where a rule has one amount for single and head of household, one for a joint return and one for married filing separately, the filing status picks its own.
The 1.8.0 additions (cross-cutting rules)
A further pass sets the engine 1.8.0 rules that cut across states: each state's treatment of a qualifying surviving spouse, how Railroad Retirement benefits reduce a retirement cap or leave an income test, which states treat 401(k), 403(b) and 457(b) money as pension income, the North Dakota qualified-dividend exclusion, the Georgia and Delaware pools that take interest and dividends, Missouri's extra head-of-household exemption, the CA, NE, VT and WI early-distribution additions (and whether they come after the credits), the taxes that survive a taxable income of zero, the Wisconsin subtraction-or-credits election and the county-rate range a request may give (IN, MD). Each is cited beside it.
The 1.8.0 final-round rule tables
Sets the final-round fields of the 51 jurisdictions' tables (the property regressions of the 3M-case sweeps and the new person facts), each with its source; zero everywhere else.
The 1.9.0 capital-loss tables
Sets each taxing jurisdiction's capital-loss rule, with its source: the federal §1211(b) limit ($3,000, $1,500 married filing separately) for the 34 states and DC that start from federal AGI or federal taxable income and for AR, MS and WI (WI also limited to Wisconsin ordinary income); MA $2,000 against interest and dividends only; AL the whole in-year loss; PA and NJ nothing (zero). Not indexed.
Qualifying surviving spouse qualifying surviving spouse returns
A qualifying surviving spouse (filingStatus qss) is one person on the return, taxed from the single figures with the state's own treatment of the status laid over them: where the state says so, the joint rate schedule, the joint standard deduction, the joint personal exemption, the joint income limits and phase-outs (only those the state sets for joint returns), the married 65+ and blindness amounts, or the head-of-household return; where the state gives the status nothing of its own, the single return. The federal figures the engine derives for the status are the federal qualifying-surviving-spouse ones (the joint standard deduction, the married 65+ amount).
Elections: claim the exclusion or not
Where claiming a retirement exclusion costs a credit, the engine computes the return each way and keeps the lower tax (on a tie, the exclusion is claimed). Arkansas: the "65 Special" credit goes only to a 65+ taxpayer who claims no retirement exemption, so each such taxpayer (per person with both ages or a per-taxpayer split, else the return) may forgo the exemption. Wisconsin: the 67+ retirement subtraction forfeits the credits, so on a joint return with the spouse's age and own amounts the return without the subtraction (and with the married couple credit) is weighed against the return with it.
Engine 1.12.0 credit rules
The nonrefundable earned income credits (SC, UT, DE), NJ's property tax deduction and credit, IL's property tax credit and CA's renter's credit, and the federal EIC table the state shares are of.
Engine 1.13.1 rental real estate rules
Rental real estate (rentalNetIncome): PA and NJ let a rental loss offset no other class or category of income (rental_loss_no_offset); every other taxing state takes the federally allowed loss as it starts from federal AGI or the federal schedule. GA and DE count net rental income in their retirement-income pools.
Income tests on the whole year (part-year / nonresident) only when the caller gives a part-year or nonresident residency
On a part-year or nonresident return's state-source computation, every income test (phase-outs, cliffs, the exclusion percentages) reads the whole year's federal AGI, as the forms set those amounts from the whole year's income before prorating them.
Income normalisation and attribution
The income total every income test uses
Other ordinary income + retirement distributions (before any exclusion) + conversion + federally taxable Social Security + long-term gains + Railroad Retirement Tier 2. It stands in for federal adjusted gross income in every threshold, cliff and phase-out below; state subtractions do not reduce it.
Short-term gains exempt
Short-term gain (a part of other ordinary income) leaves the base; it stays in the income total above.
Nesting the income subsets
Public pension ⊆ pension income ⊆ retirement distributions; military pay ⊆ distributions and apart from pension income; wages ⊆ other ordinary income. Each subset is clamped into its parent, so an inconsistent input cannot exclude dollars that are not there.
Attributing income to each spouse joint returns with each spouse's own amounts given
With a caller's split (the API's spouse object), each spouse's own distributions (employer-plan money included), pension, public pension, conversion, wages and military pay; spouse 2's shares are clamped into the household totals and spouse 1 gets the rest. Without a split, in per-person mode, every item is divided 50/50. Social Security is divided by each spouse's own gross benefits where the caller gives spouse.socialSecurityGross, else 50/50; other ordinary income and gains are always divided 50/50 where a rule needs a per-person amount. The split is used only where a state's rule is per taxpayer; household totals stay authoritative for the base and the income tests.
Early IRA distributions
The IRA and employer-plan dollars each person took before 59½: the amount the caller gave, else every such dollar of a person under 59 at the end of the year (none of an older person, or when the age is not given). Where the state keeps its retirement break only for some federal early-withdrawal exceptions, the other early dollars leave the retirement pool and are taxed as ordinary income; the exception is the caller's, else death for a survivor's benefits, disability for a disabled person, else none. Where the state taxes only the part over the IRA basis, the part within it is left out altogether. A kept exception passes the state's IRA age gate. The additional state tax on the early dollars with no exception is added before the credits, or after them where the state says so (next steps).
Disability pay taxed as ordinary income only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where only government disability plans are subtracted, disability pay (read as a non-government plan's; a government disability pension is entered as a public pension) leaves the retirement dollars and is taxed as ordinary income, each spouse's share by the split, else half.
The plan's minimum retirement age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where the state reads it, the minimum retirement age of the plan paying a person's disability pay (the filer's, or the spouse's on a joint return), when given: from that age the pay is a pension. Not given, each state keeps its own reading.
Disability pay only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Each person's disability pay (the caller's disabilityIncome, part of the pension income) is excluded up to the state's cap (all of it where there is none), for a totally and permanently disabled person where the state requires it and below the age where there is one; on a joint return without per-person amounts the cap is doubled only when a second person can qualify (the spouse also said to be disabled where the state requires it). Where the state reduces it, the total is reduced dollar for dollar by the return's income over the threshold (one threshold per return; the separate-return threshold where there is one). The excluded dollars leave the base before any retirement exclusion. Where the state reads it, the plan's minimum retirement age (when given) replaces the age at which the pay stops being excluded.
Disability pay below the pension age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Disability pay of a person under the state's age (read as reported federally as wages, before the plan's minimum retirement age) is not pension income for the pension deduction: it leaves the retirement income and is taxed as other ordinary income. Each spouse's own share as given (else half) at their own age; a person whose age is not given keeps it in the pension income. Before the plan's minimum retirement age (when given) the pay is wages too.
Disability pay outside the pension subtraction only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where disability pay received before the employer's minimum retirement age is wages, the pay leaves the pool the pension subtraction draws on and re-enters the base in full after the exclusions, unless planMinimumRetirementAge says the person has reached that age. Per person by the caller's split, else equally. A person at or past the plan's minimum retirement age (when given) receives a disability pension, which stays in the pool.
Federal survivor annuity of a survivor at the age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
A survivor at or above the age excludes the whole federal government survivor annuity (the civil service annuity received as a survivor): each spouse's own annuity by the caller's split, else equally; on the household path the filer's.
Survivor benefits only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
A survivor's retirement income (the caller's survivorBenefits: the person's pension and IRA income is received as a beneficiary; without a spouse object the fact describes the household). Where the state deducts survivor benefits, the pension part leaves the base before Ohio-style income tests (the IRA part stays: an inherited account was payable without the death). Where the state gives a surviving spouse its own deduction, up to the state's amount of that income is deducted and the rest gets no own-plan retirement deduction (it is not the survivor's own plan) and is taxed as ordinary income; military pay keeps the military rule. The surviving-spouse deduction is the higher amount when the deceased spouse would have reached the state's age (the deceased spouse's age, when given).
Disability pay at the age deduction's age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where the state lets a person at the age deduction's age claim the disability subtraction instead, the capped disability pay of each such person is set aside here and weighed against the age deduction later.
Keeping the per-spouse shares inside the household joint returns with each spouse's own amounts given
After the public-pension and employer-pension carve-outs, if the two spouses' remaining shares add up to more than the household's exclusion-eligible distributions (an inconsistent split), spouse 1's share is reduced so they do not.
Railroad Retirement benefits only when the caller gives Railroad Retirement benefits
Railroad Retirement benefits are never taxed by a state (45 U.S.C. §231m). Tier 2 (railroadRetirementTier2) is in the income total the tests use but never in the base. Tier 1 (railroadRetirementTier1) is a part of the gross benefits (socialSecurityGross); its share of the taxable benefits is taken out of the Social Security every state rule sees, so a state that taxes Social Security never reaches it. Where a state's worksheet says so, the benefits reduce a retirement cap or subtraction (ID, IN, MD, ME, MN: both tiers; MI: the taxable railroad benefits); Minnesota's and Utah's Social Security rules test an income without them, Minnesota's, New Jersey's and California's retirement income tests an income without Tier 2; Ohio and Delaware test their own AGI everywhere, which never holds the benefits.
The capital-loss deduction the state allows
With a net capital loss (capitalLoss): the smaller of the loss and the state's limit (the federal $3,000 / $1,500 where the state follows the federal return; MA $2,000, and no more than the interest and dividends); AL the loss less the part carried in, unlimited; PA and NJ none. It comes off the income total the income tests use (and the Social Security worksheets' income); the gross-income filing test (LA) reads the total before it. Engine 1.13.1: with a rental loss (rentalNetIncome below 0, the federal Schedule E line 26 amount) the state allows, the whole loss where the state starts from federal AGI or follows the federal schedule, none in PA and NJ (rental_loss_no_offset): it comes off the same income the same way; a rental profit is other ordinary income.
Each spouse's own Social Security joint returns
On a joint return, each spouse's own Social Security is the spouse's share of the benefits by spouse.socialSecurityGross when the caller gives it (Tier 1 railroad benefits left out), else half each. It is what the per-spouse rules read: Colorado's per-spouse subtraction, Rhode Island's per-spouse modification, and the Maine, Maryland and other retirement caps reduced by the benefits each spouse received (with each spouse's own railroad benefits where the state counts them).
401(k), 403(b) and 457(b) distributions only when the caller gives 401(k), 403(b) or 457(b) distributions
Employer-plan distributions (employerPlanDistributions) are part of the IRA-sourced money. Where the state's pension rule covers employer plans (Maryland's pension exclusion, Rhode Island's Schedule M modification) they count as pension income, up to the distributions not already pension or military pay; everywhere else they are treated like IRA distributions.
Qualified dividend exclusion only when the caller gives qualified dividends
The share of the qualified dividends (qualifiedDividends, part of the other ordinary income, never more than it less the wages) that the state excludes leaves the other ordinary income.
Exclusions: military pay, pensions, Social Security, retirement income, conversions and gains
Income tests on the state AGI
Where the state's retirement income test and federal-tax percentage read its own AGI, the income total is federal AGI less the state subtractions the inputs carry: the military pay excluded and every capital gain (long- and short-term).
Military retirement pay
The state's military rule runs first, on military pay alone, per taxpayer: each spouse's own pay at their own age when attributed, otherwise half each at the household age on a joint return. Exempt dollars leave the base; the rest become pension dollars for the general retirement rules. Where the state lets a disabled retiree qualify at any age, a disabled person is treated as having reached the rule's age.
Military pay received by a survivor only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where the state excludes it, military pay a survivor receives (the person's survivor fact; on the household path the top-level fact, for the household) is excluded in full, at any age, apart from the military rule's caps.
Employed military retiree under the age
Where the state lets a retiree under its military age qualify while employed with enough employment income to have to file a federal return, a retiree whose own wages (the household's on the household path) reach the federal filing threshold for the status is treated as having reached the age.
One taxpayer's military exemption
Exempt: all of it (below the age split, up to the younger cap). Capped: up to the cap for the age tier, plus the earned-income bonus below the age split when the taxpayer's own wages exceed the threshold, less the taxpayer's own Social Security where the rule says so. Percentage: the percentage (below the age split, up to the younger cap). Then the income limit: above it the exemption is lost, or phased out over the range where one is set.
One military cap per joint return joint returns
On a joint return the cap is one amount for the couple, over the pay of the spouses who pass the age test, reduced by the household's Social Security where the rule says so, then the income test.
No retirement deduction on a separate return married filing separately
Where the statute gives married taxpayers the deduction only on a joint return, a married-filing-separately return excludes no military pay and no non-covered public pension.
Income tests without exempt pay
Where the state's return does not report exempt income, the income that sets the retirement-exclusion bands and tests (New Jersey's line 27) leaves out the military pay the state exempts and the disability pay it excludes; the federal-AGI-like total the other tests use keeps them.
Military exclusion reduces other caps
Where the statute says so, the military amount a taxpayer excluded reduces that taxpayer's general retirement-exclusion cap, their age-65 subtraction, or both. A survivor's military pay (a surviving-spouse military deduction) reduces neither, where the state says so.
Military pay barred from the general exclusion
Where a state's military rule leaves dollars taxable and bars them from the general retirement exclusion, they are added back to the base after the exclusions. No jurisdiction currently does this.
Capital-loss deduction off the base
The deduction comes off the other ordinary income (negative income, as Form 1040 line 7a is), so the base and every state-AGI figure summed from it carry it; WI no more than Wisconsin ordinary income (Schedule WD line 28(c)). States whose base is federal taxable income (with the caller's figure) already have it there and take it only once. Engine 1.13.1: the allowed rental loss comes off the same way, on its own line (rental_loss_deduction).
Non-covered public pension excluded in full only when the caller says the pension was not covered by Social Security
Only when the caller says the public pension was not covered by Social Security: the pension takes the uncapped public-pension exemption below (per taxpayer, without using the general retirement exclusion).
Public pension exemption
Public-pension dollars leave the base, uncapped or up to the per-taxpayer cap (each spouse's own public pension against their own cap when attributed), without using up the general exclusion the remaining distributions may claim. Capped-out public dollars stay taxable and cannot draw the private exclusion.
Public pension exemption reduced by the Social Security exemption
The capped public-pension exemption is reduced by the Social Security the state exempts (Tier 1 railroad benefits left out): from age 50, and under that age where the benefits are exempt as disability benefits (said to be, or not said where the state reads the fact for the household — see the disability-age rule). On the per-person path each spouse's own share (by spouse.socialSecurityGross, else half each); on a joint return with a spouse object but no ages, the spouse's own share when only the primary's benefits are said not to be disability benefits.
Civil Service Retirement System annuity excluded only when the caller says the pension was not covered by Social Security
A federal civil service annuity from service not covered by Social Security (the caller says pensionPublicSsCovered: false — CSRS; FERS service is covered) is excluded in full, each spouse's own as given (else half).
Employer pension exemption
Employer (defined-benefit) pension dollars, public or private, leave the base; IRA dollars keep the capped exclusion.
Colorado: per spouse, own ages joint returns with the spouse's age given
Per spouse at their own ages (both ages known): each spouse's own distributions and own Social Security (by the spouse's stated gross benefits, else half) through the subtraction below, at that spouse's age; the income test for ages 55 to 64 uses the joint income total. A conversion is taxed in full, except where the state counts it as a taxable IRA distribution: then it draws what is left of the same subtraction after the distributions.
Colorado: per spouse, household age joint returns
Joint return without the spouse's age: still per spouse, each at the household age, with the distributions split by the caller's split or 50/50 and Social Security by the spouse's stated gross benefits, else 50/50. A conversion is taxed in full, except where the state counts it as a taxable IRA distribution: then it draws what is left of the same subtraction after the distributions.
Colorado: one filer
Otherwise (single, separate and head-of-household returns): one subtraction on the whole amount. A conversion is taxed in full, except where the state counts it as a taxable IRA distribution: then it draws what is left of the same subtraction after the distributions.
Social Security below the exemption age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Where Social Security is exempt only from an age unless it is disability benefits, a person under that age whom the caller says does not receive disability benefits keeps their share of the taxable benefits in the base (the share by the spouse's stated gross benefits, else half). Not said: the benefits stay exempt, the earlier result. Disability benefits, and benefits under that age not said to be other benefits (which stay exempt), also reduce the public-pension exemption at any age where the state says so.
Social Security disability: not said, and the household fact only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Benefits of a person under the age whose disability status is not said are exempt as disability benefits everywhere — they also reduce that person's public-pension exemption. Without a spouse object the top-level socialSecurityDisability describes both halves of the household's benefits.
Colorado Social Security and pension subtraction
65 or older: Social Security fully subtracted; pension and annuity income up to $24,000 less the Social Security subtracted. 55 to 64 with income at or below the threshold: the same with a $20,000 cap. 55 to 64 above it: one shared $20,000, Social Security first. Under 55: no subtraction, except a survivor's death benefit (its own step).
Which Social Security threshold applies
Joint returns use the joint threshold; head of household uses it too where the state says so, otherwise the single one; married filing separately uses its own threshold where set, else the single one. Benefits are tested against the income total above.
Social Security exempt
None of the federally taxable benefit enters the base.
Social Security: exempt up to a threshold, then all
At or below the threshold nothing enters; above it the whole federally taxable amount does (a cliff).
Social Security: the federal amount
The federally taxable amount enters the base as it is.
Social Security: a share of gross benefits above a threshold
At or below the threshold nothing enters. Above it, 12.75% of gross benefits, capped at the federally taxable amount; without gross benefits the engine estimates them as the taxable amount divided by 0.85.
Social Security: stepped subtraction
At or below the threshold nothing enters. Above it, 10% of the benefit enters for each $4,000 of income over ($2,000 married filing separately), or part of one, up to all of it.
Social Security: ratable phase-out
At or below the threshold nothing enters. Above it the share entering rises in proportion over the next $10,000 of income, up to all of it.
Social Security: credit phase-out
The credit removes the tax on benefits at or below the threshold. Above it the credit falls by 2.5% per dollar over; the engine carries this as the taxed share of benefits rising by that rate divided by the tax rate per dollar over, up to all of it.
Social Security: age and income test
Exempt only at full retirement age (67) or older with income at or below the threshold; otherwise the whole federally taxable amount enters.
Social Security: income strictly below the limit
Where the statute says "less than", income exactly at the limit does not qualify.
Social Security: Colorado age bands (Social Security alone)
The same age bands as the Colorado subtraction, on Social Security alone. In a calculation Colorado always takes the joint subtraction above; this branch serves callers of the Social Security rule by itself.
Rhode Island: per-spouse age test joint returns with the spouse's age given
With both ages known, each spouse's own share of the benefits (by the spouse's stated gross benefits, else half) is exempt only if that spouse is at full retirement age, against the joint income test.
Does a conversion draw the retirement cap?
Where the state lets a conversion draw the capped exclusion, and the filer is at or above the conversion age (the state's own pooling age where it has one; any age for a disabled person where the state says so), the conversion is pooled with distributions against the cap. A spouse who elects not to claim the exclusion draws none of it.
Retirement exclusion per spouse (both ages known) joint returns with the spouse's age given
Full-exclusion states exclude each qualifying spouse's own dollars. Capped states give each spouse the single cap for their own age against their own eligible dollars (pension dollars only where the exclusion is pension-only; employer dollars only below the IRA age), less their military exclusion and their own Social Security offset (by the spouse's stated gross benefits, else half). Per-return states (and the pooled-if-both-qualify rule when both qualify) apply the joint cap to the couple's pooled eligible dollars when either spouse qualifies. The income tests then apply once to the summed deduction.
Income-tested percentage of distributions
Distributions are deductible at the percentage for the income band (joint column for joint returns, and for head of household unless it uses the single column). Where the state says so a conversion draws the same percentage; otherwise it is taxed in full. In per-person mode the excluded amount is shown for each spouse in proportion to their own distributions (reporting only).
The percentage table
The deductible share by income. Single, head-of-household and separate filers: 100% from $0; 85% from $75,000; 70% from $77,500; 55% from $80,000; 40% from $82,500; 25% from $85,000; 10% from $87,500; 5% from $90,000; 2.5% from $95,000; 0% from $100,000. Joint filers: 100% from $0; 85% from $100,000; 70% from $105,000; 55% from $110,000; 40% from $115,000; 25% from $120,000; 10% from $125,000; 5% from $130,000; 2.5% from $140,000; 0% from $150,000. The table lives in code; these values are read back from it.
Conversion pooled with distributions
The conversion joins the distributions against the one cap (with a spouse split in a per-taxpayer state, each spouse's own distributions and conversion against that spouse's cap). Nothing of the conversion is added separately.
Pension-only exclusion
Only pension and annuity dollars draw the capped exclusion; IRA dollars and conversions are taxed in full.
No retirement exclusion (age deduction instead)
Distributions and conversions stay in the base; the age deduction below applies against any income.
Retirement exclusion (household)
The distributions eligible for the exclusion go through the exclusion below. Taxable public-pension dollars left by a cap are not eligible; below the IRA age only employer-plan dollars are.
Pensions exempt at any age
Below the full exclusion's age a pension annuity is still exempt — the recipient met the plan's retirement requirements — and only the IRA and 401(k) money in the distributions is taxed (each spouse's own when both ages are known).
Retirement exclusion per spouse (declared split) joint returns with each spouse's own amounts given
With a spouse split in a per-taxpayer state, each spouse's own eligible dollars draw that spouse's single cap (less their military exclusion); an income limit then applies once to the sum.
Conversion taxed or exempt
In full-exclusion states a conversion is exempt at the qualifying age (at any age where the state says so). Elsewhere, unless pooled above, it is ordinary income taxed in full.
Social Security: alternate subtraction
The Social Security subtraction is the larger of the regular one and the alternate one: the filing status's maximum less the rate times the provisional income (the income total less taxable benefits, plus half the gross benefits) above the threshold, at most the taxable benefits. Needs the gross benefits; without them only the regular subtraction applies.
Full exclusion
All distributions are excluded at or above the exclusion age; below it they are taxed.
Graduated exclusion by income band
Below the exclusion age nothing is excluded. Otherwise the share of the exclusion granted falls with income (Social Security left out); in the middle bands it is a percentage by filing status of the whole pension, limited to the pension, where the state's worksheet says so, otherwise of the capped amount. The separate-return cap applies where set. Engine values, single and head of household: 100% from $0; 37.5% over $100,000; 18.75% over $125,000; 0% over $150,000; joint: 100% from $0; 50% over $100,000; 25% over $125,000; 0% over $150,000; separate: 100% from $0; 25% over $100,000; 12.5% over $125,000; 0% over $150,000.
Income limit on the exclusion
When the income total (Social Security left out where the state says so) exceeds the limit, the exclusion is lost (a cliff), reduced dollar for dollar after the cap (subtractive), or phased out in proportion over the range. Head-of-household and separate returns use their own limits where the state sets them.
Cap by age tier
The full cap at or above the exclusion age, the lower cap at or above the partial age, otherwise none. Joint returns use the joint cap; every other status the single cap.
Cap reduced by Social Security
The cap is reduced dollar for dollar by Social Security received: gross benefits when supplied, otherwise the federally taxable amount, with the Railroad Retirement tiers the state's worksheet names. In per-person mode each spouse's cap is reduced by that spouse's own benefits (by the spouse's stated gross, else half).
The capped deduction
Deduction = the smaller of the eligible distributions and the cap, then reduced by the income limit above; the rest of the distributions stays in the base.
Separate-return phase-out range married filing separately
On a married-filing-separately return the capped exclusion phases out over the state's own separate-return range instead of the single one.
One taxpayer's cap joint returns with the spouse's age given
For per-spouse calculations, each spouse's cap is the single-column cap for their age tier.
Long-term gains in the base
Where gains are taxed as ordinary income: net long-term gain less the flat exclusion (never below zero), times the inclusion share. Elsewhere none enters.
Capital gain cap
Net capital gain above the cap is exempt; the partial inclusion applies to the gain up to it (once per return: the gain is not attributed to a spouse).
Short-term gains in the retirement pool
Where the state's retirement exclusion covers the net capital gain without a short/long split, the net short-term gain (inside other ordinary income, never more than its non-wage part) moves into the pool beside the long-term gain; in per-person mode half is each spouse's.
Interest and dividends in the retirement pool
Where the state's retirement exclusion covers investment income, the other ordinary income that is not wages (interest, dividends and other income; the API's ordinaryIncome) joins the pool, split half and half between spouses in per-person mode. Internal callers whose ordinary income is untyped keep it out.
Gains deduction on a separate return married filing separately
Married filing separately takes its own (half) flat gains deduction.
Gains exclusion capped by federal taxable income
The flat gain exclusion is at most the set share of federal taxable income: the caller's figure where supplied, otherwise the income total less the federal standard deduction, its age and blindness amounts and the federal senior deduction (not below zero).
Retirement and investment pool per spouse joint returns with the spouse's age given
Each spouse's pool = own distributions + own conversion + half the long-term gain in the base (+ half the interest and dividends where the state pools them, pool-ordinary) + (where the state counts earned income) up to the earned-income amount of their own wages, against the cap for their own age. The pool above the caps is taxed.
Retirement and investment pool
Distributions + conversion + long-term gain in the base (+ wages up to the earned-income amount per qualifying person) form one pool against the cap for the household age (each spouse's own pool and cap with a split in a per-taxpayer state). The pool above the cap is taxed as ordinary income; conversions and gains are not added separately.
Capital loss inside the retirement pool (GA, DE)
Where gains join the retirement pool (GA, DE), the pool holds gains net of losses: the exclusion is at most the pool less the deducted loss (half each spouse in per-person mode); the loss itself leaves the base at capital-loss-deduction.
Public pension not covered by Social Security only when the caller says the pension was not covered by Social Security
Only when the caller says the public pension was not covered: the smaller of the public pension still in the base and the cap, reduced above the income start (by a percentage per step, or linearly over a range). Where it is an election instead of the Social Security exclusion, the engine keeps whichever excludes more.
Non-covered pension: age test and shared cap only when the caller says the pension was not covered by Social Security
Where the state sets them: only a recipient at or above the age qualifies (each spouse's own public pension in per-person mode); the cap is reduced by the Social Security received (gross when supplied) and by the military pay the same deduction already excluded. A disabled recipient qualifies from the lower disability age where the state sets one.
Deductions, exemptions and age subtractions
Additional standard deduction at 65
The unmarried amount for a single or head-of-household filer 65 or older, the married amount for each spouse 65 or older, added to the standard deduction before any phase-out.
Additional standard deduction for blindness only when the caller says a person is blind or disabled
The unmarried amount for a blind single or head-of-household filer, the married amount for each blind spouse, added to the standard deduction before any phase-out. Age and blindness are separate boxes, so a person 65 or older and blind gets both.
Low-income retirement income subtraction
While the income total is less than the status limit, each person at or above the age subtracts the pension and IRA dollars still in the base, up to the amount (per spouse with their own amounts; on the household path at the household age, twice the amount on a joint return). Not on a separate return, whose limit is both spouses' combined income. It does not forfeit the credits.
Standard deduction phase-out
Above the start the deduction is scaled by 1 − (income − start) / width, down to zero, with head-of-household and separate starts where the state has them; where the state says so a head of household never gets less than the single deduction at the same income. Where the state rounds the reduction, it is rounded down to that multiple before it is taken. Where the state says so the income is its own (the base after its subtractions) rather than the income total.
Phase-outs on the state AGI
Where the state's worksheets start from its own AGI, the standard-deduction and personal-exemption phase-outs test the state base before deductions (federal AGI less the exempt Social Security, the pension deduction and military pay), not the federal AGI.
Standard deduction limited at high income
Above the income threshold the deduction (with its age and blindness amounts) is limited to the status amount: the state adds the rest back. On the component path only; where the caller supplies federal taxable income that figure is used as given.
Standard deduction limited at high income (percentage)
Above the first income threshold the standard deduction (with its age and blindness amounts) is reduced by the first rate times the income above it (up to the second threshold) plus the second rate times the income above the second threshold, by at most the stated share of the deduction. Married filing separately has its own thresholds.
Standard deduction chart on state AGI
From the status's start the maximum deduction loses a fixed step for each band (or part) of state AGI (the income in the base before any deduction), down to a floor.
Exemption phase-out on state income
The exemption the engine carries as the deduction is lost in whole steps for each step (or part) of income over the start, or linearly over the range; the income here is what enters the state base (exempt Social Security left out).
Taxpayer credit instead of a deduction
No deduction is subtracted: the deduction amount (plus the federal additional amount per taxpayer 65 or older) becomes the base of the credit applied after the schedule. The federal blind amount joins the base the same way, per blind person.
Personal exemption
The joint amount on a joint return, the head-of-household amount where set, otherwise the single amount.
Head-of-household additional exemption head of household
A head of household adds the state's additional exemption to the personal exemption.
Exemption set by income
The amount per exemption is the first tier whose income limit the income total does not exceed (joint limits for joint returns, and for head of household where set), else the amount above the tiers; two exemptions on a joint return, one otherwise. It replaces the flat exemption.
Exemption tiers on the state's own income
The tiers (and the joint filing credit's income limit) test the state base before exemptions, with the Social Security and military pay the state deducts already out, instead of the federal-style income total.
Exemption phase-out
Above the filing status's start the exemption is scaled by 1 − (income − start) / range, down to zero.
Low- and middle-income exemption
At any age, per exemption (the filer, the spouse on a joint return and, where the state counts them, each dependent the caller lists): the amount less the filing status's rate times the income total above its base, not below zero, and none once the income total is over the status's limit.
Exemption for blindness only when the caller says a person is blind or disabled
An extra exemption for each blind person (the filer, and the spouse on a joint return). Where the state's exemption is for a person who is blind or disabled, a disabled person below the state's age limit (if any) qualifies too, one exemption per person either way.
Veteran exemption
An exemption for each veteran. The inputs name a veteran only through military retired pay: each person with their own military pay (at least a cent, compared in cents: the primary's own pay is the household total less the spouse's, and its binary rounding residue is not a shortfall) who is not receiving it as a survivor (without a spouse object, the household's pay counts one person).
Income exclusion for disability only when the caller says a person is blind or disabled
Up to the amount of income for each disabled person, while the income total is under the limit, taken against the base (the engine does not know each person's own income; taxable income cannot go below zero).
Dependent exemptions and deductions only when the caller lists dependents
An amount per dependent subtracted like the personal exemption: the state's flat amount, or the stepped per-exemption amount the filer gets, or the state's own income steps; nothing above an income limit where there is one; a percentage phase-out per income step where there is one; one more for a dependent in an age band or a student up to an age, for a dependent born in the year, and for a disabled dependent; a deduction per dependent beyond the first on joint and head-of-household returns; and a child deduction by an income table for dependents under an age. A head of household's status exemption that already holds one dependent's amount counts one fewer. Where the state says so, the phase-out is measured on the state AGI (the base before deductions).
Age subtraction
At or above the age: the single amount, or the joint amount on a joint return (both spouses at the household age). In per-person mode, half the joint amount (or the single amount) per qualifying spouse. Plus the low-income amount below the income test; less the military exclusion where the statute says so; limited to the spouse's own income where the statute says so. Where the statute counts income from any source, the taxable remainder of the spouse's own public pension is part of that own income. Where the state says so, the Social Security that offsets a person's amount is that person's own.
Age amount on a separate return married filing separately
A married person filing separately adds the married age amount, not the unmarried one.
Age subtraction for a disabled person only when the caller says a person is blind or disabled
Where the state gives its age subtraction to a permanently and totally disabled person at any age: per disabled spouse in per-person mode; on the household path below the age, one amount per disabled person, reduced as at the age.
Age subtraction reduced by Social Security and public pension
Each qualifying taxpayer's amount is reduced by their own taxable Social Security (half each on a joint return) and their own public-pension exemption. On the household path, a disabled filer under the age is reduced by that person's own half of the household amounts where the statute says so.
Extra exemption at 65 for low income
One more exemption per taxpayer at or above the age when the income total (conversions left out where the state says so) is at most the filing status's limit.
Age exemption stepped down by income
For each taxpayer at or above the age (each spouse on a joint return): the full amount while the income total is at most the status's start, then less the decrement for each width of income (or part of one) above it; head of household reads the joint column where the state says so. Where the state says so, a blind person qualifies too, with one exemption per person.
Federal senior deduction taken against the state base
For each taxpayer 65 or older: the amount, reduced by the rate times the income total above the status's start (joint start on a joint return); none for married filing separately. In the states whose base is federal taxable income it is taken only when the caller does not supply that figure (it is already in it).
Disability exemption instead of the regular ones only when the caller says a person is blind or disabled
A person who is blind (or disabled) takes the state's disability exemption instead of their own regular and age exemptions; the other spouse keeps theirs. Where that exemption replaces the dependents' exemptions too, the larger of the two routes is taken.
Age deduction against any income
The amount per taxpayer at or above the age, reduced dollar for dollar by income (taxable Social Security left out) over the limit; on a joint return the combined amount is reduced once by the joint excess. A person at or above the no-income-test age keeps the full amount. Engine 1.14.1: on a part-year return (Form 760PY, age_py_on) the worksheet's full-year amount, the cap less the whole year's AFAGI excess (age_py_afagi: federal AGI less the year's taxable Social Security), times each person's own ratio (age_py_factor; line 15, "Multiply Column A by Column B").
Age deduction or disability subtraction only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Each person at or above the age claims either the age deduction or the disability subtraction set aside earlier; the age deduction is counted only for the persons claiming it and reduced once by the joint income excess. Every combination is tried and the largest total subtraction is kept, the age deduction on a tie. The disability subtraction chosen leaves the base. A person at or above the no-income-test age keeps the full amount.
Separate returns share the couple's exemptions married filing separately
Where the state pools the couple's exemptions on separate returns and gives each half: the dependents' amounts are halved, and when the caller gives the other spouse's age or blindness, the age and blind amounts of both spouses are pooled and halved (otherwise the filer's own facts stand for both).
Federal civil service annuity deduction only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
For each federal civil service annuitant at or above the age (a survivor at any age), the annuity up to the amount, less the gross Social Security that annuitant received (each spouse's share by the stated gross, else half) and, where the state counts them, their Railroad Retirement benefits. A joint return without spouse ages: the household convention (twice the amount when the household age qualifies, the household's benefits).
Pension exclusion below the age, and the low-income exclusion
A person at or under the age excludes employer and government pension income up to the amount (one exclusion per person, so military pay already excluded counts toward it; IRA money and disability pay do not qualify). A person at the age or disabled, with earned income under the limit and income at most the limit, excludes the amount; on a joint return both must qualify, with doubled limits and amount.
Subtraction at 100
Each individual at least the age subtracts the first income up to the amount: with the spouse's own amounts, each qualifying spouse's own income left in the base (the joint items half each); otherwise the household's, one amount per qualifying person at the household age.
Survivor benefits below the age only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
Below the pension subtraction's age, a person whose pension and IRA income is received as a beneficiary subtracts it up to the cap. Where the state says so, the person's own taxable Social Security received as survivor benefits shares the same cap.
The under-65 disabled subtraction only when the caller gives the person facts (a civil service annuity, disability pay, Social Security disability, survivor benefits, an IRA basis or an exception)
With no one at the age, a disabled person with disability pay qualifies: the base (the joint base on a joint return), at most the disability pay, less the nontaxable Social Security and Railroad Retirement benefits and half the federal AGI over the floor (the both-qualified floor when both spouses are disabled). Not on separate returns.
Other retirement income exclusion
A household with a filer (a spouse on a joint return) at the age, total income (Tier 2 railroad benefits left out) at most the limit and wages at most the limit excludes other income up to the part of the pension-exclusion maximum (the dollar maximum, or in the higher bands the band percentage of total income) the pension exclusion, conversions included, did not use; on a joint return with one spouse at the age, only that spouse's income (own wages, half the household items, and the spouse's own distributions and conversion left after their own exclusion). Age only: disability does not qualify.
Born before 1946
A filer (on a joint return the older spouse) at or above the age: public pensions are subtracted without limit (the private cap is the cap less the public amount, so the public amount over the exclusion taken is added), and the interest, dividend and gain deduction takes the cap less the retirement, military and taxable railroad subtractions (non-wage ordinary income and gains are read as interest, dividends and gains).
No exemptions above an income limit
Above the federal AGI limit (the joint limit on a joint return) there is no exemption allowance at all: the personal amount (Illinois carries it as its standard deduction), the 65+ and the blind exemptions are all zero.
Age 65 subtraction reduced by income
With the filer (or either spouse on a joint return) at or above the age: the filing status's base amount less the nontaxable Social Security (gross less taxable) and less the rate times the income total above the start (the joint start only when both spouses qualify), not below zero. None on a separate return. With Social Security but no gross figure the nontaxable part is unknown and nothing is subtracted.
Nontaxable Social Security without the gross
With Social Security but no socialSecurityGross, the subtraction's nontaxable benefits are the taxable part / 0.85 less the taxable part (the gross is at least that), instead of dropping the whole subtraction at the first dollar of benefits.
Age standard deduction instead of the retirement subtraction
When the older spouse is between the two ages, a deduction per return against all income: the filing status's amount less the military pay the state excluded and, at or below the lower tier's age, less the personal exemptions. It replaces the retirement subtraction: when it is larger, the retirement income that subtraction removed returns to the base and this deduction is taken instead.
Age standard deduction: the non-covered pension add-on only when the caller says the pension was not covered by Social Security
Above the Tier 3 ages, a household with a public pension from employment not covered by Social Security (pensionPublicSsCovered: false) adds the add-on to the age standard deduction before the military pay comes off.
Deduction for Social Security and Medicare paid on wages
Per person, the rate times that person's own wages, at most the per-person maximum; not combined or moved between spouses. On a joint return the spouse's wages come from the spouse amounts; without them the wages are the filer's.
Two-income subtraction joint returns with each spouse's own amounts given
On a joint return with the spouse's own amounts given: each spouse's income in the base (own wages, own retirement income left after their own exclusions, own conversion, half the joint items), and the smaller of the two, at most the maximum, is subtracted. Where the state says so (Maryland, Worksheet 13D line 4), each spouse's income is net of that spouse's own subtraction at 100.
Income of a person 100 or older
At the state's age a person's income is exempt, taken from the base before deductions: all of it for an unmarried filer or a separate return, half the joint income per centenarian spouse on a joint return (the equal-attribution convention; all of it when the household age is used for both). The centenarian does not also take the state's 65-or-older exemption.
Deduction and exemptions phased out in steps
Above the start, the state's modified income keeps the standard deduction and the exemptions at one less the step share for each step (or part) over it, none once that reaches zero.
Exemptions against the base-rate income first
The exemptions offset the income taxed at the base rate (wages, pensions, IRA dollars and conversions after the wage deduction) first. On a separate return what they cannot offset is lost; the other statuses carry it to the short-term gains, then interest and dividends, then long-term gains (see the short-term gains step).
Property tax deduction (NJ)
NJ-1040 lines 40a-41: the property taxes paid (or the rent share), at most the cap ($15,000; half on a separate return), off taxable income.
Rent and homeowner property tax deductions (MA, IN)
MA: half the rent paid on the principal residence, at most $4,000; IN: the rent, at most $3,000, and the property tax paid on the principal residence, at most $2,500; each per return and smaller on a separate return, off income.
Medical expense deduction (NJ) and exemption (NM)
NJ: the medical expenses over a share of New Jersey gross income (line 29); NM: $3,000 when the filer or spouse is 65 or older and the medical care expenses are at least $28,000 (not on a separate return); off income.
Property tax deduction or credit (NJ)
Worksheet H: the deduction when it lowers the tax by at least the credit ($50; half on a separate return), otherwise the refundable credit (at or below the filing threshold only at 65 or older, blind or disabled).
Taxable income
State taxable income
Other ordinary income + Social Security, retirement income, conversion and gains left in the base − standard deduction − personal exemption − age subtractions.
Starting from federal taxable income only when the caller supplies federal taxable income (the planner; not the API)
When the caller supplies federal taxable income (the planner does; the API does not), the base starts from it, adds the gains in it (less the state's gain subtraction), and subtracts the state's own exclusions and subtractions; the state's deduction is not subtracted again.
Federal income tax deduction only when the caller supplies federal tax
Only when the caller supplies federal tax. Full: the federal tax plus the net investment income tax. Capped: the federal tax (without the net investment income tax where the state says so) up to the cap, which loses 20% of itself for each band of income from the start (joint and head-of-household returns on the joint bands, separate returns half the cap). Where the state subtracts them (the full deduction), less the federal refundable credits the caller gives, never below zero.
Federal income tax deduction by percentage band only when the caller supplies federal tax
Only when the caller supplies federal tax: the percentage of the federal tax for the band that holds the state AGI (inclusive tops; none above the last band), at most the cap (the joint cap on a joint return).
Detail record
The bases, exclusions and subtractions are recorded per person (or for the household) for the breakdown.
Rule names in the detail record
Each person's record names the military, retirement and age rule the state applies.
Income for the low-income tests
For Iowa's low-income rules: taxable income plus the standard deduction and the exemptions and senior deductions subtracted (the federal senior deduction too where the caller supplies federal taxable income).
No tax at or below zero
State taxable income at or below zero returns a tax of 0 (credits are not refundable), unless the state has a tax computed apart from taxable income that still applies (next step).
Taxes that survive a zero taxable income
Where the state's forms compute them apart from taxable income, the early-distribution tax, the minimum tax and the capital-gains surcharge still apply when taxable income is zero or less: the return goes on with taxable income 0 (no schedule tax), and only the credits the state allows against them reduce them.
Tax: the schedule, recapture, gains rates and minimum tax
Low Income Tax Table lookup
The 2025 Arkansas Low Income Tax Tables for one or no dependents (single, head of household, joint), on AGI rounded to the dollar; code constants, not scaled for later years.
Low Income Tax Table, two or more dependents only when the caller lists dependents
The head-of-household and joint tables for two or more dependents (2025 tables), on AGI rounded to the dollar; code constants, not scaled for later years.
High-income table
Above the threshold the whole net income is taxed at the low rate on a first band and the top rate above it, less a bracket adjustment that falls by a fixed step for each band (or part) of income over the threshold and ends at zero.
Each spouse's own zero-rate band joint returns
On a joint return the first (zero-rate) bracket is widened to the sum over the spouses of the smaller of the band and that spouse's income (own wages, retirement and conversion income by the caller's split, everything else half each), and the brackets above shift with it (engine 1.6.0: with the spouses' ages known, see the next step).
Zero-rate band: whose income stayed taxable joint returns with the spouse's age given
When the spouses' ages are known, the retirement and conversion income left in the base is attributed to the spouse whose own distribution stayed taxable (each spouse's own dollars less their own exclusion), not by each spouse's share of all distributions; wages and the joint items as above.
Zero-rate band: the household split joint returns with each spouse's own amounts given
With each spouse's own amounts but no ages, the retirement income left in the base is attributed by the distributions each spouse still has there — own distributions less own exempt military pay and own pensions exempt at any age — not by each spouse's share of all distributions.
Short-term gains at their own rate
The short-term gains in the base are taxed at their own rate instead of on the schedule. Deductions and exemptions come off the schedule income first; any left over reduce the short-term gains. Where the state orders them (engine 1.8.0): the exemptions left after the base-rate income reduce the short-term gains, then interest and dividends (taxed on the schedule), then long-term gains.
Separate-return scaling married filing separately
For the halved-joint rule, taxable income is doubled before the schedule and the result halved.
A separate tax for each spouse joint returns with each spouse's own amounts given
On a joint return with each spouse's own amounts, each spouse is taxed on the schedule on their share of taxable income, the share being their state AGI over the couple's (a spouse with negative income: none): own wages, own distributions less own military pay, own conversion, own share of the taxable Social Security (by the gross split, else half) and half the other ordinary income; gains are subtracted. The form rounds the share to a whole percent; the engine uses the exact share. Without the spouse's amounts the schedule applies once.
The rate schedule
Each bracket's rate on the part of taxable income inside it, summed. No rounding: the result is carried in full precision.
The rate schedule as printed (New York)
New York's Tax Law §601 prints its 2026 schedules as whole-dollar base amounts plus the rate on the excess over the bracket's start; each base is the previous base plus the previous bracket's full tax, rounded to the dollar. The engine uses those bases wherever it reads the schedule (the tax, the §601(d-1) recapture worksheets, a part-year return's full-year tax). Other states' whole-dollar schedules are the revenue department's rounding of statutory rates and stay on the exact sums.
High-income table in place of the schedule
Above the threshold the rate schedule's result is replaced by the high-income table's (see its step).
Fixed amount above the zero bracket
Once taxable income passes the threshold a fixed amount is added (halved with the schedule for a separate return).
Tax-benefit recapture
On state AGI (the income in the base before deductions) above the start, the recapture below is added. Where the state publishes the worksheets' constants, they are used (the step below) in place of the computed benefits.
The recapture worksheets
For each bracket below the filer's top one, its benefit (flat rate times the bracket bottom, less the schedule tax on it, less the lower brackets' benefit) is phased in over $50,000 of income above the larger of $107,650 and the bracket bottom. Fully phased in, all taxable income is taxed at the top rate. Where the first worksheet applies to taxable income below its bracket, the flat rate of that bracket applies to all of it, phased in the same way.
The published recapture worksheets
The worksheets with the state's published constants: while taxable income is at most the top of the bracket holding the start, the flat rate of that bracket times taxable income less the schedule tax, times the phase-in; above it, the tier's recapture base plus its incremental benefit times the phase-in over the tier bottom; above the top threshold, the top rate times taxable income. Every phase-in fraction is rounded to the fourth decimal place.
Add-back and recapture
On state AGI (the income in the base), the add-back and the recapture below are added to the schedule tax.
Rate phase-out add-back (Table C)
A fixed amount per step (or part) of income over the start, up to a maximum, by filing status. The table lives in code; the state page prints engine values.
Personal tax credit table (Table E)
The decimal of the first row whose income limit holds the state AGI, by filing status (.75 down to .01; none above the last row). The table lives in code (statutory, unindexed; the TY2025 table is the 2026 proxy).
Benefit recapture (Table D)
Three tiers per filing status (separate returns use the single tiers); each adds a fixed amount per step (or part) of income over its start, up to its own maximum.
Own schedule for long-term gains
The gain in the base (at most the taxable income) is taken out of the schedule and taxed at the lower gains rate up to the first ordinary bracket's top, stacked on the ordinary income, and at the upper rate above; this replaces the schedule part of the tax, and amounts added on top of the schedule before it (a fixed amount, recapture) are kept.
Alternative capital-gains tax
The schedule part of the tax is the smaller of the regular schedule tax and the schedule tax on income without the gain plus the alternative rate times the gain; amounts added on top of the schedule before it are kept.
Floor under the alternative gains tax
Where the statute says so, the alternative tax's ordinary part is taxed on at least the taxable income taxed at rates below the alternative rate (the top of the last such bracket, in taxable-income dollars, at most taxable income), and the alternative rate applies to the rest of taxable income.
Alternate tax for low incomes
Joint returns and heads of household: the schedule tax is replaced by the rate times the low-income income over the limit (the higher limit when the filer or spouse is 65 or older) when that is smaller; at or below the limit it is zero.
Minimum tax
Above the income threshold the tax before credits is at least the rate times the income total.
Additional tax on early distributions
The state's share of the federal additional tax on early distributions (the rate on each early dollar with no exception): added before the credits (Arkansas, Nebraska, Vermont), or after them in California and Wisconsin (see the step after the credits).
Credits
Qualified-individual credit table
The full credit up to a net-taxable-income limit, a fixed step less for each hundred-dollar row above it, none past the last row (the 2025 table; code constants, not scaled for later years).
Per-exemption credit
The credit per exemption: two on a joint return, one otherwise, or the state's own count for a head of household. Where the state sets an income limit there is no credit above it (the joint limit for joint returns and heads of household).
Personal tax credit (a decimal of the tax)
A credit of the Table E decimal times the tax before credits (the schedule with the add-back and recapture), by state AGI and filing status; carried with the personal credits.
Credit per dependent only when the caller lists dependents
A credit per dependent, under the same income cutoff and phase-out as the personal credits where the state has them (each dependent credit loses the same amount per step, floored as a group).
Senior credit
The credit per taxpayer at or above the age: two on a joint return at the household age, one per qualifying spouse in per-person mode. A head of household's extra personal credit is not a second senior credit.
Extra credit at 65 without a retirement exemption
One more credit per taxpayer 65 or older who takes no retirement exclusion: per person in per-person mode; on the household path every 65+ taxpayer gets it only when no retirement exclusion was taken. Whether to forgo an exclusion for it is weighed by the elections step (the lower tax is kept).
Credit for blindness only when the caller says a person is blind or disabled
The credit for each blind person.
Low income credit
Under the federal AGI limit, the credit for the AGI band times the exemptions (the filer, the spouse on a joint return, one more per person 65 or older); none on a separate return.
Credit for qualified individuals
Arkansas's Additional Tax Credit for Qualified Individuals on net taxable income, doubled on a joint return.
Child credits only when the caller lists dependents
A credit per dependent at or under the child age and another per older dependent; none above an income limit where there is one; where the credit is a share of the federal child tax credit, the share of the federal credit the household is allowed (the nonrefundable part up to the federal tax, the refundable part from earned income); reduced per dollar over a threshold, or by a percentage per thousand dollars over a start, where the state says so. Also a credit per disabled dependent child at or under an age, while income is at most the limit. Where the state says so, the child credit is prorated by the state AGI (the base before deductions) over the federal AGI when the state AGI is lower. The federal tax that limits the nonrefundable part is the tax before credits when given; with only the tax after the nonrefundable credits, any tax left means the whole credit was allowed, and none left means the nonrefundable part is taken as zero. Where the state says so, the refundable part for three or more children is the larger of the earned-income route and the Social-Security-tax route.
Family size and household credits
Family size credits: a share of the tax left after the personal credits, by family size (the filer, the spouse on a joint return, and the dependents — every dependent, or only qualifying children, as the state says; at most the state's largest size) and the income total, from the state's table (separate returns: half every limit where the state says so). Household credits: an amount by income (single) or by income and household size (joint and head of household; separate returns their own table).
Retiree credits
The retirement income credit by the retirement income left in the base (one per return) and a senior credit per return, both while income less exemptions is under the limit; the retirement income credit on the pension income of the persons at the age, at most the base less all Social Security and less household income over the household base; and the senior head of household credit on taxable income, at most the cap, for a filer at the age whose head-of-household qualifying person died in one of the two previous years, while income is at most the limit.
Personal, senior and blind credits phased out
Above the status threshold each personal, senior and blind credit loses the amount for each step of income (or part of one), not below zero; the separate step applies to married filing separately.
Credit for severe disability only when the caller says a person is blind or disabled
One more credit for each disabled person (where the state says so, each blind person too: one per person either way) while the income total is at most the limit.
Low-income exemption credit
A credit per exemption (one, two on a joint return) while taxable income, the income less exemptions, is below the limit.
Taxpayer tax credit
The credit rate times the credit base, less the phase-out rate times taxable income above the filing status's base, not below zero.
Taxpayer credit phase-out counts all taxable Social Security
The phase-out income adds back the Social Security the Social Security credit offsets, since the state's taxable income includes it.
Married couple credit joint returns with each spouse's own amounts given
Joint returns with the spouse's age and a spouse split only, and only when no retirement exclusion was taken: the rate times the lower-earning spouse's wages, up to the maximum.
Marriage credit joint returns with each spouse's own amounts given
On a joint return with each spouse's own amounts: the tax on joint taxable income on the joint schedule less the single-schedule tax on the lesser-earning spouse's income minus the state's amount (half the joint standard deduction) and on the rest of joint taxable income; at most the cap where there is one; none when that is zero or less. Each spouse's income counts to the extent it is in the state base: own wages, own share of the retirement income left in the base (own distributions less own excluded military pay), of the conversion and of the Social Security in the base (by the gross split, else half).
Credit for past military service
On the return that taxes the military pay (the election above), the credit per qualified person — each spouse with military pay when their own amounts are given, else one — less the rate times federal AGI over the start, not below zero. Military pay under the state's minimum (a cent, compared in cents: the pay left in the distributions after the pensions carries the binary rounding residue of the sums) makes no one a qualified person.
Two wage earner credit joint returns with each spouse's own amounts given
Joint returns with each spouse's own amounts only, both spouses with wages: the rate times the lower earner's wages, counting at most the maximum.
Spouse tax adjustment joint returns with each spouse's own amounts given
Joint returns with each spouse's own amounts: each spouse's own income in the base (own wages, their share of the retirement and conversion dollars left, half the joint items, less their own age deduction) less the personal exemption and the 65+ and blind amounts must be positive for both. Above both limits the full amount; otherwise the tax on the joint taxable income less the tax on the two parts the worksheet splits it into. Reported as the two-earner credit.
Joint filing credit joint returns with each spouse's own amounts given
Joint returns with the spouse's age and a spouse split only, income under $500,000 (the state's own income where it tests that), and each spouse with at least $500 of wages, retirement or conversion income: a share, by taxable income, 15% from the first dollar of tax; 10% over $50,000; 5% over $75,000, of the tax (after the credits before it, where the state says so), at most $650.
Retirement credit instead of the Social Security and military credits
Per person at or above the age (a birth-year cutoff), less the phase-out rate times the income total above the filing status's start. It cannot be combined with the Social Security or military credit, so the engine takes whichever is larger; choosing it puts back the tax the Social Security credit removed.
Military retirement credit
The credit rate times the military pay.
Senior credit per return
For a filer at or above the age: the single amount (single, separate) while federal AGI is at most the single limit; for a head of household, or a joint return with both spouses at the age, the joint amount while AGI is at most the joint limit (one spouse: the smaller joint amount). Nonrefundable, against the state tax before the local tax.
Tax forgiveness
Eligibility income (the state's taxable income; twice the filer's own on a separate return, since the table uses joint income) at or below the base forgives the whole tax after the other credits; each step (or part) above it forgives the step share less. Each dependent child (a dependent under 19, a full-time student under 24, or a disabled dependent) raises the base by the per-dependent amount.
Earned income and poverty level credits
The federal earned income credit (the step below) is computed from the credit rate on earned income (the wages) up to the maximum, less the phase-out rate on the larger of the income total and earned income over the start (joint start on a joint return), none above the investment-income limit, by qualifying children (dependents under 19, students under 24, disabled at any age; at most 3); without one the filer or a spouse must be under the age. Not on a separate return. The state takes its share (a different share for a single or head-of-household filer without a child). The poverty level credit is a share of earned income while the larger of the income total and earned income is under the poverty guideline for the persons on the return. Both are nonrefundable; their local counterparts reduce the county tax.
The federal earned income credit
The federal earned income credit the state credits read: the credit rate on earned income up to the maximum, less the phase-out rate on the larger of the income total and earned income over the start (joint start on a joint return) — where the state says so, measured from the income at which the maximum is reached when that is higher; none above the investment-income limit; by qualifying children (dependents under 19, students under 24, disabled at any age; at most 3); without one the filer or a spouse must be at least the minimum age where the state sets one and under the maximum age. Not on a separate return.
State earned income credit as a share of the federal credit
Where the state's credit is simply a share of the federal earned income credit (the step above), that share, nonrefundable, after the other credits the form takes first.
Credits cannot make the tax negative
The credits are subtracted and the result floored at zero.
Tax at most the federal tax only when the caller supplies federal tax
The tax after the nonrefundable credits is at most the federal tax before credits: the caller's figure for it when given, else the caller's federal tax when that is the planner's own figure (no credits taken). With only the tax after the federal credits, no cap is applied (a cap below the real one would understate the tax). The form applies the cap while the net state adjustments (increasing less decreasing) are under its limit; the adjustments the inputs carry all decrease income, so the cap always applies.
Single-filer tax reduction for low incomes
Single filers: the tax after credits is at most the low-income income over the limit (the higher limit at 65 or older), so zero at or below it.
No tax below the filing threshold
While the income in the base after the subtractions (before the age deduction, the standard deduction and the exemptions) is less than the status amount, the tax is zero; separate returns use the single figure. Reported as the low-income tax adjustment.
Arkansas Low Income Tax Tables
A single, head-of-household or joint filer whose total income from all sources (Social Security, the whole gain and every exempt dollar) is within the table may give up the military, pension and IRA exemptions: the table's tax on AGI (no standard deduction; the partial gain exclusion kept) plus the early-distribution tax, less the personal and senior credits, the 65 Special for every 65+ taxpayer and the qualified-individual credit on that AGI. The lower of the two results is taken.
Filing status 4 (separate columns on the joint return) joint returns with each spouse's own amounts given
On a joint return with each spouse's own amounts, each spouse's column (own wages, retirement and conversion income left in the base and early IRA dollars; half of the joint items; half of every deduction) is taxed on its own schedule, the qualified-individual credit per column and the other credits from the total; the lower of the two results is taken.
No tax at low income, and the limited-income cap
With the state AGI (the income in the base before deductions and exemptions) at most the filing status's limit, the tax is at most the rate times the AGI above the no-tax amount, so none at or below it. Not on a separate return.
No tax at or below the filing threshold
Where the state imposes no tax on a filer whose gross income (New Jersey line 29: total income less the pension and other-retirement exclusions) is at or below the filing threshold, the tax after credits is zero at or below the status's amount (single and married filing separately; joint and head of household). One cent above it the whole tax is due.
Nonrefundable earned income credits
SC, UT, DE and VA: a share of the federal EIC, nonrefundable, with the other credits (SC at most $200; DE, or its refundable share, the larger; VA, the larger of it and the credit for low-income individuals ($300 per exemption at a family income within the poverty guideline), or the refundable share, the larger).
Property tax credit (IL)
Schedule ICR: a share of the property tax on the principal residence, nonrefundable, at AGI at most $250,000 ($500,000 joint).
Renter's credit (CA)
Form 540 line 46: $60 ($120 joint, head of household, surviving spouse), nonrefundable, for a renter at CA AGI at most $55,830 ($111,660), with no property tax given.
School property tax credit (WI)
Form 1 lines 16a-16b: a share of the property taxes plus rent constituting property taxes, the base at most $2,500 (half on a separate return), nonrefundable.
Property tax credit (CT)
Schedule 3: the property tax, at most $300, less a share for each AGI step over the start, nonrefundable.
After credits: county tax, surcharges and surtaxes
Flat tax on every required return
A flat amount on every return the state requires: the income total at least the federal filing threshold for the status (the standard deduction with its 65+ amounts; a fixed amount when married filing separately); none when the filer or spouse is blind where the state says so. It is owed even with no taxable income.
County income tax
The county rate times state taxable income, after credits and not reduced by them — except the county's own earned income and poverty level credits (the federal earned income credit times the multiplier times the rate, and earned income times the rate), which reduce the county tax to at most zero. The rate is the population-weighted average of the official county rates, or the county rate the request gives in localTaxRate (within the state's lowest and highest rate). Engine 1.12.0: with a county code in localities, that county's rate; Maryland's Anne Arundel taxes on marginal brackets and Frederick at the rate of the tier the income falls in, on the whole income (its local credits at that rate).
Capital-gains surcharge
When the income total exceeds the threshold, the rate times net long-term gain.
Surtax on high income
The rate times state taxable income over the filing status's threshold.
Early-distribution tax after the credits
Where the state adds its early-distribution tax after the nonrefundable credits (California, Wisconsin), it is added to the tax left after them, so no credit offsets it.
Locality lookup
A request names its local jurisdictions by official code; the code is looked up in the compiled registry (research/data/state-tax-localities.json and its official tables).
County code
A county code (Maryland, Indiana) sets that county rate, and Maryland's brackets, before the state return is computed.
Local income taxes
Each local tax on its own base: NYC (its schedules on New York taxable income, less the household credit on federal AGI), Yonkers (its surcharge share of the net state tax) and Iowa school districts (the surtax percent of the Iowa tax after credits) on the state return; Ohio school districts (traditional: Ohio MAGI less exemptions; earned: wages and self-employment, at most MAGI; the senior citizen credit at 65), Ohio municipalities, Pennsylvania EIT and Philadelphia (with its School Income Tax), Kentucky, Kansas City and St. Louis, and Wilmington on earned income only; Michigan cities on income less pensions, annuities and Social Security, less the exemptions; Oregon Metro and Multnomah on Oregon taxable income less public pensions over their thresholds. A workplace pays its nonresident rate on its wages; a Pennsylvania resident is credited the nonresident EIT paid elsewhere in the state; otherLocalTaxCredit comes off the separate resident returns.
Part-year local lines
NYC (IT-360.1 Part 4): its schedules on the period's taxable income, the household credit on the year's federal AGI × full months / 12; Yonkers (Part 5): line 65 (or 72) × the line 73 income percentage × the Yonkers resident rate; Ohio earned-income-base districts (SD 100 lines 29-33): the period's wages, at most its income; PA EIT (CLGS-32-1 Local Worksheet): the year's earned income / 12 × the months at the residence. Engine 1.14.0: Philadelphia, the resident rate of each half of the year (the period's days in each half over the half's days) on the period's compensation; Ohio traditional-base districts (SD 100 line 22), line 5 x the residency factor (days / 365, four places); Ohio municipalities, Lexington, the resident rate on the period's income; Kansas City / St. Louis, the year's wages x (1 - daysOutside / work days); Metro / Multnomah (MET-40-NP / MC-40-NP), Schedule INC line 29M less the deductions x line 29M / 29F (six places), the exemption in full; Detroit (Form 5120 Column A), the exemptions x the resident months / 12; Grand Rapids (Schedule TC), the full exemptions against the resident income.
Local amounts in a later tax year
Engine 1.12.1: in a projected year (projection with indexing "law", and the planner's later years) each locality's amounts move the way its law moves them (research/data/state-tax-localities.json indexing, with official sources): Philadelphia's enacted schedule (the Wage and Earnings Tax by July 1 steps, a calendar year at the average of its two rates; the Net Profits Tax and the School Income Tax by tax year; the 2029 step "and subsequent years"); Portland Metro's thresholds as published for 2027 and no settled year after (the index and rounding of the yearly adjustment are not published); Multnomah County's rates, whose enacted rate increase has no settled start year, settled through 2026; every other kind fixed until the jurisdiction changes it. A year past the last settled one is refused by POST /api/state-tax and held, with a disclosure, by the planner. With indexing "inflation" the local amounts are held.
Refundable state credits
The credits paid beyond the tax (reported in refundableCredits; netTax = totalTax less them): earned income credits as a share of the federal EIC with each state's own age band (OK on the 2020 federal credit, DC's own childless schedule, the CalEITC table, MN's Working Family Credit), the NYC EIC and school tax credits, and the property-tax, renter, grocery and senior credits of MA, MI, NJ, ID, HI, NM, OK, AZ, NY, RI, WV, ME, DC, MN, MO, WI, IN and MT, each on its own income measure. Engine 1.13.1: a part-year NYC resident's school tax credits (the Table 2 proration chart and the rate-reduction amount on IT-360.1 line 47; IT-203 lines 60 / 60a for a part-year state resident).
Part-year and nonresident returns only when the caller gives a part-year or nonresident residency
A part-year resident's or nonresident's tax by the state's own method: R, the full-year resident tax × the state's income ratio; D, the tax on the state's own income with the form's prorated deductions, exemptions and credits; C, the full-year tax less a credit for the non-state share; S, the tax on the state's own income, nothing prorated (each state's method, ratio, rounding and prorated items on its page). The earned income and low-income credits are left out; a nonresident's retirement income is refused (4 U.S.C. §114).
Per-spouse proration items only when the caller gives a part-year or nonresident residency
Each prorated item (standard deduction, exemptions, age amounts, retirement caps) scaled by the average of the two spouses' own factors weighted by each spouse's own part of the item, so the total is each spouse's item times their own factor; MO's per-spouse percentages weight the per-spouse taxes of MO-1040 line 30.
The apportionment ratio only when the caller gives a part-year or nonresident residency
The state's own income over the whole year's (the state's own AGI or federal AGI, as the form says), rounded to the form's places (cut where it says so), bounded at 1 where it says so; a zero or negative whole-year income by the form's own rule, and refused where the form says nothing and there is tax to apportion.
The prorated items only when the caller gives a part-year or nonresident residency
The standard deduction (with its 65 / blind additions), personal exemptions, the age-65 subtraction, dependents, per-person credits, the retirement exclusion caps, the federal tax deduction: the ones the form prorates, × its ratio, days or months.
R: the full-year tax × the ratio only when the caller gives a part-year or nonresident residency
The resident tax on the whole year × the ratio; CT and WI on the larger of the state's and the whole year's income; CA's tax-rate method; MT's two ratios; MD's 505 (the state tax × Maryland taxable income / all taxable income, plus the special nonresident tax of 505NR line 17); VA's 763 (taxable income × the allocation percentage, then the schedule).
C: the full-year tax less a nonresident credit only when the caller gives a part-year or nonresident residency
IA 126: the tax less the tax × (one less the Iowa percentage); ME Schedule NR: the tax × non-Maine AGI / Maine AGI; OH IT NRC: the tax × the non-Ohio portion / Ohio AGI, cut to four places.
D and S: the tax on the state's own income only when the caller gives a part-year or nonresident residency
The state-source input (residency.stateIncome) taxed by the resident rules with the form's prorated items scaled (D) or as is (S); KY's personal credits × Kentucky AGI / federal AGI; AL's federal tax deduction × Alabama AGI / federal AGI; the IN county tax only for a part-year resident who lived there on January 1.
Conventions: rounding and later years
Rounding
The engine does not round, except where a form rounds a computed amount: South Carolina rounds the reduction of its income-adjusted deduction down to a whole ten dollars, and the engine does the same. Otherwise brackets, phase-outs and credits are computed in double precision, and the API returns the tax unrounded. Step functions that the forms define in whole steps use ceilings (Minnesota's Social Security and public-pension steps, Connecticut's exemption, add-back and recapture steps, California's credit phase-out) or floors (Oregon's federal-tax bands). Where a state's instructions look tax up in a table of income bands, the engine applies the rate schedule to the exact amount, so results can differ from the table by a few dollars. The pages on this site show amounts rounded to the cent.
Later years: projection
A later tax year is estimated by projecting the rules year's configuration: each dollar amount and each birth-year age cutoff moves by the rule the indexing registry (research/data/state-tax-indexing.json) gives it, from the state's own law: indexed amounts by the cumulative CPI factor, the increase rounded the statute's way (a figure carried from the previous year gets that year too, at the factor's average annual rate); fixed-in-law amounts held; enacted schedules followed, then held or indexed (a whole bracket table a statute prints for a later year applies with its rates); birth-year cutoffs one year older per year; an amount the statute defines from another (a derived rule) recomputed from that amount as projected; attained ages held; amounts no official source settled held (and refused by the API when they bear). Rates and flags are never touched; the rules year at a factor of 1 is the configuration unchanged. The planner's out-years, POST /api/state-tax projection and libstatetax call this one function; the registry is compiled into state_tax_indexing_data.h (scripts/gen_state_tax_indexing.mjs, gated fresh).
How one amount moves
For one registry parameter at a year and factor: the multiplier (CPI and federal: the factor, times the factor's average annual rate for each year the engine's figure is older than the rules year), the scheduled year whose value applies and whether the year is past the schedule (then the multiplier for the years since, when the statute indexes after it; or, for a schedule stated in an earlier year's dollars, the multiplier for the years since that year in every scheduled year), or the years a birth-year cutoff moves. The API's projection block reports it per parameter.
Later years: indexing "inflation"
The optional mode (planner stateThresholdIndexing, API projection.indexing "inflation"): the convention of the planner before engine 1.10.0, reproduced exactly from the registry's inflation_mode data. Every amount marked uniform (the field list the retired scaler multiplied, with its flag conditions) is multiplied by the cumulative factor, unrounded; a bracket table's lower bounds and every upper bound below the open top likewise; every other amount is held at its 2026 figure; schedules, derived amounts and value years are not applied. Birth-year age cutoffs move one year per year, as in the default mode. test_state_tax_projection.c proves it byte-identical to the retired scaler on every state, year and factor.
The lines the worked examples show
The engine records these as it computes (its detail record); the state pages print them for each worked example. The documentation build checks that they add up: taxable income = the income in the base − the deductions, exemptions and age subtractions − the federal-tax deduction (floored at zero), and tax = schedule tax + the additions and adjustments − the credits used + the county tax, surcharge and surtax.
| Record field | Line | Step |
|---|---|---|
agi_proxy | Income total used by the income tests | The income total every income test uses |
short_term_gains_exempt | Short-term gain exempted (not in the base) | Short-term gains exempt |
military_excluded | Military pay excluded (not in the base) | Military retirement pay |
retirement_excluded | Retirement income and conversions excluded (not in the base) | The capped deduction |
earned_income_excluded | Wages inside the retirement exclusion (not in the base) | Retirement and investment pool |
noncovered_pension_excluded | Non-covered public pension subtracted (already out of the retirement line below) | Public pension not covered by Social Security |
ordinary_in_base | + Other ordinary income in the base | State taxable income |
ss_in_base | + Social Security in the base | Which Social Security threshold applies |
retirement_in_base | + Retirement income in the base | The capped deduction |
conversion_in_base | + Roth conversion in the base | Conversion taxed or exempt |
ltcg_in_base | + Long-term gain in the base | Long-term gains in the base |
standard_deduction | − Standard deduction | Standard deduction phase-out |
personal_exemption | − Personal exemption | Personal exemption |
senior_total | − Age subtractions and deductions | Age subtraction |
subtractions_other | − Other subtractions (wage contributions, two-income) | Deduction for Social Security and Medicare paid on wages |
federal_tax_deduction | − Federal income tax deduction | Federal income tax deduction |
taxable_income | = State taxable income | State taxable income |
zero_band_width | Joint zero-rate band after per-spouse widening | Each spouse's own zero-rate band |
bracket_tax | Tax from the rate schedule | The rate schedule |
short_term_gain_tax | + Short-term gains at their own rate | Short-term gains at their own rate |
bracket_cliff | + Fixed amount above the zero bracket | Fixed amount above the zero bracket |
recapture | + Tax-benefit recapture | The recapture worksheets |
ct_addback | + Rate phase-out add-back (Table C) | Rate phase-out add-back (Table C) |
ct_recapture | + Benefit recapture (Table D) | Benefit recapture (Table D) |
cg_schedule_adjustment | ± Own gains schedule (replaces the schedule tax on the gain) | Own schedule for long-term gains |
cg_alt_adjustment | − Alternative capital-gains tax saving | Alternative capital-gains tax |
lowinc_alt_adjustment | − Alternate low-income tax saving | Alternate tax for low incomes |
min_tax_topup | + Minimum tax top-up | Minimum tax |
tax_before_credits | = Tax before credits | Minimum tax |
credit_exemption | Per-exemption credit | Per-exemption credit |
credit_senior | Senior credit | Senior credit |
credit_blind | Blind credit | Credit for blindness |
credit_disabled | Disability credit | Credit for severe disability |
credit_taxpayer | Taxpayer tax credit | Taxpayer tax credit |
credit_married_couple | Married couple or marriage credit | Married couple credit |
credit_joint_filing | Joint filing credit | Joint filing credit |
military_credit | Military retirement credit | Military retirement credit |
credit_low_income | Low income credit | Low income credit |
credit_qualified | Credit for qualified individuals | Credit for qualified individuals |
ss_credit_restored | + Tax on the credited Social Security (retirement credit chosen) | Retirement credit instead of the Social Security and military credits |
credit_two_earner | Two wage earner credit | Two wage earner credit |
credit_retirement | Retirement credit | Retirement credit instead of the Social Security and military credits |
credit_tax_forgiveness | Tax forgiveness | Tax forgiveness |
credits_applied | − Credits used (never more than the tax) | Credits cannot make the tax negative |
lowinc_tax_adjustment | − Low-income reduction or table (after credits) | Single-filer tax reduction for low incomes |
fed_tax_cap_adjustment | − Down to the federal tax (after credits) | Tax at most the federal tax |
credit_limited_income | − No-tax / limited-income reduction | No tax at low income, and the limited-income cap |
local_tax | + County income tax | County income tax |
cg_surcharge | + Capital-gains surcharge | Capital-gains surcharge |
surtax | + Surtax | Surtax on high income |
flat_tax | + Flat tax on a required return | Flat tax on every required return |
cg_excise | Capital-gains excise | Washington capital-gains excise |
dependent_exemption | − Dependent exemptions and deductions | Dependent exemptions and deductions |
capital_loss_deduction | − Capital-loss deduction | Capital-loss deduction off the base |
early_distribution_tax | + Additional tax on early distributions | Additional tax on early distributions |
credit_dependent | − Dependent and child credits | Child credits |
credit_household | − Family size and household credits | Family size and household credits |
credit_retiree | − Retirement income credits | Retiree credits |
credit_senior_other | − Senior credits (per return; senior head of household) | Retiree credits |
disability_income_excluded | Disability pay excluded before the base | Disability pay |
credit_earned_income | − Earned income credit (State) | Earned income and poverty level credits |
credit_poverty | − Poverty level credit (State) | Earned income and poverty level credits |
local_credits | Local earned income and poverty level credits (inside the county tax) | County income tax |
age100_subtraction | Subtraction at 100 (inside the age subtractions) | Subtraction at 100 |
joint_tax | Joint return tax, when two separate columns cost less | Combined separate return (two columns on one form) |
ar_status4_adjustment | − Filing status 4 (separate columns) when lower (after credits) | Filing status 4 (separate columns on the joint return) |
tax | = Tax | Credits cannot make the tax negative |
railroad_excluded | Railroad Retirement benefits kept out of the base (Tier 2, and the taxable Tier 1) | Railroad Retirement benefits |
qualified_dividends_excluded | Qualified dividends excluded (not in the base) | Qualified dividend exclusion |
early_distribution_tax_after_credits | + Additional tax on early distributions (after the credits) | Early-distribution tax after the credits |
rental_loss_deduction | − Rental-loss deduction | Capital-loss deduction off the base |
Later years: projection
The engine's tables are for tax year 2026. A later year is projected by state_tax_project_config()
(backend/src/state_tax.c:6404): each state's dollar amounts and birth-year age cutoffs move the way that state's law moves
them, rule by rule from the indexing registry, each with its source (how projection works; each state page's
"After 2026" section lists its rules). The planner's out-years, the API's projection and the library call the same function.
The numeric configuration fields below are not amounts and are never projected:
| Field | Meaning | Why it is not projected |
|---|---|---|
taxpayer_credit_rate | Taxpayer tax credit rate on the deduction base (UT); nonzero means no deduction is subtracted | A rate. |
taxpayer_credit_phaseout_rate | Taxpayer credit reduction per dollar of taxable income over the base | A rate. |
ltcg_inclusion_ratio | Share of net long-term gain entering the base (0 = all of it) | A share. |
cg_alt_rate | Alternative maximum rate on net long-term gain | A rate. |
cg_own_rate_low | Own lower capital-gains rate (two-rate schedule) | A rate. |
cg_own_rate_high | Own upper capital-gains rate (two-rate schedule) | A rate. |
cg_surcharge_rate | Surcharge on net capital gain above an income threshold | A rate. |
cg_excise_rate | Capital-gains excise rate (no-income-tax state) | A rate. |
cg_excise_high_rate | Additional excise rate above the high threshold | A rate. |
top_surtax_rate | Flat surtax on taxable income over the threshold | A rate. |
local_tax_rate | Default local rate (overridable per request) | A rate. |
military_pct | Share of military pay exempt (percent rule) | A share. |
military_credit_rate | Credit rate on military pay in the base (credit rule) | A rate. |
married_couple_credit_rate | Married couple credit rate on the lower-earning spouse's earned income | A rate. |
min_tax_agi_rate | Minimum tax as a share of federal AGI above the threshold | A rate. |
noncov_pension_phaseout_step_pct | Share of the subtraction lost per step | A share. |
lmi_rate_single | Reduction per dollar of AGI above the base, single | A rate. |
lmi_rate_mfj | Same, MFJ | A rate. |
lmi_rate_hoh | Same, HOH | A rate. |
lmi_rate_mfs | Same, MFS | A rate. |
fed_senior_phaseout_rate | Reduction of each senior deduction per dollar of AGI above the start | A rate. |
std_phaseout_round_down | The standard-deduction phase-out's reduction is rounded down to a multiple of this (0 = unrounded) | A rounding unit, not an amount that indexes. |
wage_contrib_deduction_rate | Deduction for the Social Security and Medicare paid on wages, as this rate of each person's wages (0 = none) | A rate. |
short_term_gain_rate | Short-term capital gains are taxed at this rate instead of the schedule; exemptions left over reduce them (0 = schedule) | A rate. |
limited_income_rate | Rate of that limited-income cap (0 = none) | A rate. |
ss_alt_rate | Reduction of the alternate subtraction per dollar over the threshold | A rate. |
senior_income_sub_rate | Reduction per dollar of AGI over the start | A rate. |
std_limit_rate1 | Limitation per dollar of AGI between the two starts | A rate. |
std_limit_rate2 | Limitation per dollar of AGI above the second start | A rate. |
std_limit_max_pct | Most of the standard deduction the limitation removes | A rate. |
tax_forgiveness_step_pct | Share of the tax forgiveness lost per step | A rate. |
ded_exempt_phaseout_step_pct | Share of the deduction and exemptions lost per step | A rate. |
two_earner_credit_rate | Two-wage-earner credit: rate on the lower-earning spouse's wages (joint returns, spouse split) | A rate. |
retirement_credit_phaseout_rate | Retirement credit lost per dollar above the start | A rate. |
cg_excl_fti_pct | The flat gain exclusion is at most this share of federal taxable income (0 = no cap) | A rate. |
fti_senior_phaseout_rate | Reduction of that senior deduction per dollar above the start | A rate. |
lowinc_alt_rate | Alternate tax rate on the income over the joint / head-of-household limit, when smaller | A rate. |
dep_phaseout_pct | Share of the dependent exemptions lost per step (or part) | A rate. |
dep_credit_phaseout_pct | Share of the dependent credits lost per $1,000 (or part) over the start | A rate. |
dep_child_credit_phaseout_rate | Child-credit reduction per dollar of income over the status threshold | A rate. |
fsc_pct | Family size credit: the share of the tax forgiven in each row | A share. |
early_penalty_rate | State tax per early dollar that bears the federal additional tax | A rate. |
ric_rate | Retirement income credit rate on net pension income (0 = none) | A rate. |
senior_hoh_credit_rate | Senior head of household credit rate on taxable income (0 = none) | A rate. |
eic_credit_rate | Federal earned income credit rate by qualifying children (0, 1, 2, 3+) | A rate. |
eic_phaseout_rate | Federal earned income credit phase-out rate by qualifying children | A rate. |
eic_state_pct | State earned income credit: share of the federal credit (with a child, or a joint return; 0 = none) | A share. |
eic_state_pct_nochild | State earned income credit share, single or head of household without a qualifying child | A share. |
eic_local_mult | Local earned income credit = the federal credit x this x the local rate | A multiplier fixed in the Maryland form. |
poverty_credit_rate | Poverty level credit: share of earned income while income is under the poverty guideline (0 = none) | A rate. |
high_income_low_rate | High-income table: rate on the low band | A rate. |
high_income_top_rate | High-income table: rate above the low band | A rate. |
mil_past_credit_rate | Reduction per dollar of AGI over the start | A rate. |
fit_pct | Share of the federal tax deducted in each row (none above the last) | Rates (the percentage of federal tax deductible in each band). |
local_tax_rate_min | Lowest county rate a request may give (0 = no override) | A rate. |
local_tax_rate_max | Highest county rate a request may give | A rate. |
eic_simple_pct | A nonrefundable share of the federal EIC (0 = none) | A share. |
eitc_nonref_pct | Nonrefundable earned income credit: share of the federal EIC by qualifying children (0, 1, 2, 3+) | Shares of the federal EIC. |
eitc_nonref_alt_refundable | Share of the federal EIC the filer may take refundable instead (DE); the larger is taken | A share of the federal EIC. |
pt_rent_factor | Share of rent counted as property tax (NJ 18%) | A share of rent. |
pt_credit_pct | Nonrefundable property tax credit: share of the property tax (IL 5%) | A rate. |
school_ptc_rate | School property tax credit (WI): share of the base | A rate. |
school_ptc_rent_heat | Rent constituting property taxes with heat included | A share of rent. |
school_ptc_rent_noheat | Rent constituting property taxes without heat | A share of rent. |
ct_ptc_pct | Property tax credit: reduction per step over the start | A rate. |
local_br_mode | County tax on brackets (set only by a locality code): 1 marginal, 2 the tier's rate on the whole base | A mode. |
local_br_n | Rows of the county brackets | A count. |
local_br_rate | County brackets: rate of each row, single and MFS | Rates. |
local_br_rate_joint | County brackets: rate of each row, MFJ, HOH and QSS | Rates. |
local_br_upto | County brackets: upper bound of each row, single and MFS | County brackets set only from a locality code (zero in every configuration). |
local_br_upto_joint | County brackets: upper bound of each row, MFJ, HOH and QSS | County brackets set only from a locality code (zero in every configuration). |
rent_ded_pct | Rent deduction: the share of the rent paid on the principal residence (MA Form 1 line 14, IN Schedule 2 line 1) | A share of rent. |
med_ded_floor_pct | Medical expense deduction: the share of New Jersey gross income the expenses must exceed (NJ-1040 line 31) | A share of income. |
What the engine does not calculate
- 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). Withoutlocalities, 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).
What it does not calculate for one jurisdiction is listed on that jurisdiction's page, under "What the engine does not calculate".