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.28.0, 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.
taxYear
taxYear (or tax_year) names the tax year the request is for. Absent or null: the rules year, as always. The rules year itself: the same response as without it. Any other year is refused with a 400, checked right after strict and before anything else, so a request for a year the build does not carry is never answered with the rules year's law (a later year is an estimate through projection). Not a whole number from 1 to 9999 (a string, a fraction, a boolean): a 400 naming the field. The embeddable library reports the year refusal as QCST_ERR_UNSUPPORTED, the status its typed path gives a tax_year it does not carry. In a build with QCST_WITH_TY2025, taxYear 2025 selects the 2025 rules year (state-lookup-year) for a jurisdiction whose 2025 rules are verified; the response's taxYear is the year computed and yearNotes lists what of the result is still the 2026 rules' (local taxes, credit tables). taxYear 2025 cannot be combined with projection (a projection estimates a later year from the 2026 rules): that request is refused with a 400. computeFederal with taxYear 2025 computes the federal return under the federal engine's 2025 rules year (the federal block's taxYear is 2025). Residency dates are dates of the tax year computed.
taxTable
taxTable (or tax_table): absent, null or true = the state's tax table where its form makes one mandatory; false = the rate schedule on the exact amount. Anything but a boolean is a 400 naming the field, with or without strict.
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 years of domicile where a state tests them), 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; an item that needs a dependent is false with a dependents list of []; since state engine 1.16 a child and dependent care item is false when the request has no earned income (it can apply with no dependent: care of an incapable spouse), an interest item when it has no tax-exempt interest, a U.S.-obligation item when it has no ordinaryIncome; 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.
Tips, overtime, vehicle loan interest, charity and domicile facts
qualifiedTips and qualifiedOvertime (top level and spouse.) are parts of the person's wages and together cannot exceed them (400). They, qualifiedCarLoanInterest and charityCash describe a full-year resident return: refused with residency (each state divides them by its own part-year rules). On a separate return the spouse object carries none of them. With computeFederal the federal return takes the tips and overtime (Schedule 1-A) and charityCash (170(p)); qualifiedCarLoanInterest is refused there (the federal engine has no Schedule 1-A Part IV). domicileYears is a whole number from 0 to 120.
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.
When the tax table applies
The engine is asked for the table on a full-year resident, part-year resident or nonresident return of a carried tax year (2025, 2026) unless the request says taxTable false (a part-year or nonresident return: the table its state's part-year or nonresident form uses; Oregon's OR-40-P / OR-40-N and West Virginia's Schedule A figure the tax on the rate schedule; Maryland's Form 505NR table stops at half the resident Form 502 table's threshold; New Jersey's NJ-1040NR leaves the table to the filer's choice: the schedule); a projection keeps the rate schedule on the exact amount.
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.
rules.taxTable
In a response for one of the 23 states (not a projected one): whether the table was applied, the method (table, worksheet or schedule), the line looked up, the row as printed and its tax (above an Alabama, Arkansas or New Mexico table the last row and the worksheet's tax), or the reason the schedule applied, the schedule's tax on the exact amount, the rule in words and whether the table is the published 2025 one or the 2026 one built by its rule.
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.
2025 whole-dollar returns: the request validated as sent, evaluated as entered
Golden round 11: a 2025 request for one of the 37 whole-dollar jurisdictions is validated on the caller's own amounts, then evaluated on each amount rounded to the dollar as the form enters it (ty25-whole-entries); a part of two amounts (early distributions of the IRA and employer-plan money, the out-of-state part of the tax-exempt interest) stays within their entered sum. Should the entered amounts break a rule the caller's own met, the caller's amounts are evaluated as given.
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.
unpublished figures (response)
Every response lists, in unpublishedFigures, each indexing-registry parameter whose rules-year value is the statute's own figure computed from published index data because the state has not printed it yet (the registry rule's unpublished text), when that parameter bears on this result: parameter, rule, valueYear, value, how. An empty list means no such figure was used.
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.
Interest split
inStateMunicipalInterest and outOfStateMunicipalInterest are parts of taxExemptInterest (a part not given is 0; without taxExemptInterest the total is their sum, which computeFederal also takes as Form 1040 line 2a); usObligationInterest is a part of ordinaryIncome. All three are refused with residency. inputsNotSupplied probes the part of taxExemptInterest no municipal part claims as each part, and ordinaryIncome as U.S. obligation interest.
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), except in Alabama (engine 1.21.2): each separate return deducts the joint federal tax, NIIT and refundable credits times the spouse's own federal adjusted gross income over the couple's (2025 Form 40 booklet, Line 12: "federal income tax liability must be determined by a ratio"), a part-year spouse's share then prorated as the part-year return prorates it; nor 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.
Looking up a jurisdiction for a tax year
Tax year 0 or 2026 is the rules year's configuration, exactly as the plain lookup. In a build with QCST_WITH_TY2025 (the API, the full and licensee library) tax year 2025 is a second rules year: the 2026 configuration copied at initialisation with its registry birth-year age cutoffs one year lower, the jurisdiction's verified 2025 changes (research/data/state-tax-2025/XX.json, compiled into state_tax_2025_data.h) and its 2025 hook (state_tax_2025.c) applied, rules_year 2025. Before those, the fields that model a federal amount (the federal EIC tables the federal-EIC states read, the federal standard and additional standard deduction amounts of the states whose base is federal taxable income) take the 2025 federal amounts where they hold the 2026 ones (st25_federal_coupled); a 2025 hook that applies to one jurisdiction only tests its code. A jurisdiction whose 2025 file is not verified yet is refused for 2025; any other year is not carried. The 2026 configurations are never written, so a 2026 result cannot move.
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).
Virginia: claim the age deduction and exemptions, or the low-income and earned income credits
VA §58.1-339.8(D) bars the credit for low-income individuals and both earned income credits only when the age deduction or the additional exemption for the blind or aged is claimed, so a 65+ or blind household chooses. Where forgoing them could earn a credit, the return is figured both ways — claiming them (no credit), and forgoing the age deduction and every aged / blind exemption (a 65+ disabled person's disability income subtraction then applies) — and the one that leaves less to pay after the refundable credit is kept (on a tie, claim). Not on a separate return.
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: DE filing status 4, KY filing status 2) 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. Where the state has a family size credit (Kentucky, Form 740 filing status 2) the columns are figured without it and the joint return's decimal is applied to their sum (line 21), each column keeping its own standard deduction, exclusion and personal credits floored at zero. The lower of that and the joint return is the tax; the joint return's lines stay in the breakdown.
Golden round 11 configuration: the states that tax the self-employment profit itself
New Jersey (NJ-1040 line 18, Schedule NJ-BUS-1), Massachusetts (Form 1 line 6a; line 11 is the only relief for the self-employment tax), Alabama (Form 40 Part I line 2; the SE tax is a Schedule A item), Arkansas (AR1000F line 12; the AR1000ADJ list has no SE-tax line) and Michigan (Schedule 1 line 2 adds the federal deduction back) take the Schedule C profit with no deduction for half the self-employment tax, as Pennsylvania does.
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. Louisiana: a household that owes the federal additional tax on an early IRA distribution must file (Form 1040 instructions, Chart C), so the test does not zero its tax; a qualifying surviving spouse is tested on the federal surviving-spouse threshold.
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 where a credit can apply (a joint return with the spouse's age and own amounts for the married couple credit; property tax or rent for the school property tax credit) the return without the subtraction (and with the credits) 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.
Independent-audit (g3) rules: MS early dollars, MO and OK §72(t)
MS: given early dollars decide the retirement exemption (early_given_opens_gate); MO: the federal tax deducted adds the §72(t) additional tax (fit_adds_72t); OK: the federal child credit limit leaves it out (ctc_limit_less_72t).
Library audit rules (2026-10-12)
DC: the 2026 standard deduction is the DC basic amount ($15,000 single and separate, $22,500 head of household, $30,000 joint) plus the federal additional amounts, and the federal senior deduction is taken (D.C. Act 26-416). OK: only the federal CSRS annuity paid in lieu of Social Security is excluded in full (csrs_exclusion); other government pensions draw the general exclusion. OH: the business income deduction and the flat rate on business income above it.
State engine 1.16 settled figures (2026-10-15)
PA: net profits are figured without the deduction for half the self-employment tax (se_profit_no_se_deduction).
2026 law sweep rules (st116)
The tax-year-2026 laws the library audit's law sweep found unmodelled: NY's subtraction of the federal tips deduction (Tax Law 612(c)(48)); IN's 2026-only deductions of the federal tips, overtime and vehicle loan interest deductions (IC 6-3-2-31 to -33); GA's overtime and cash tips exclusions of $1,750 each per person (48-7-27(a)(16)-(17)); AL's overtime deduction up to $1,000 per taxpayer (40-18-15(a)(29)); HI's conformity to the federal tips and non-itemizer charitable deductions (Act 35, SLH 2026); DC's federal tips, overtime and vehicle loan interest deductions (47-1803.04(e)); MI's (2026-2028), AZ's and OR's subtractions of the federal tips and overtime deductions (MCL 206.30(1)(ee); A.R.S. 43-1022(31)-(32); OR-17), OR adding the vehicle loan interest back (SB 1507); the federal tips, overtime, vehicle loan interest and non-itemizer charitable deductions in the federal-taxable-income bases of IA, ID, ND and MT, and of CO, which adds the overtime deduction back; DE's domicile test for the 60+ pension exclusion and its military amounts (30 Del. C. 1106(b)(3), SB 219); PA's Working Pennsylvanians Tax Credit (a tenth of the federal earned income credit, refundable).
Interest rules (state engine 1.16)
Per state: whether interest on other states' obligations is added, whether interest on its own obligations is added, and that interest on U.S. obligations is subtracted, each from the state's form line.
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. Golden round 3 (part-year audit): the Social Security a benefits threshold tests with (CT-1040NR/PY line 43, RI), the Social Security an income test leaves out (NJ line 27, MO, VA AFAGI), NJ Worksheet E's wages ("for the entire year") and MA's Schedule NTS-L-NR/PY line 8 state AGI are the whole year's too.
Separately on the same return (KY filing status 2, DC Calculation J)
A pass marks the two returns that let a married couple file separately on one form beside Arkansas's and Delaware's filing status 4: Kentucky's Form 740 filing status 2 (the combined separate return) and the District of Columbia's Schedule S Calculation J. Alabama has no such status (single, joint, separate and head of family only). Each is cited beside it.
Income normalisation and attribution
Net profits without the half self-employment tax
Where the state's net profits allow no deduction for half the self-employment tax (PA Schedule C: "You may not deduct ... the one-half of self-employment taxes the IRS allows"), that half, which federal AGI and so the earned income in the request took from the profit, goes back into the base. Each spouse's profit is the caller's own and never below zero, so no loss crosses a class or a spouse.
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. Each income line a threshold reads (this total and the states' own AGI lines) is rounded to cents first, as the form's line is, so a sum of cent amounts that a binary double holds a hair under a threshold tests as the amount it is.
Short-term gains exempt
Short-term gain (a part of other ordinary income) leaves the base; it stays in the income total above.
Service, 59 1/2 and veteran facts (state engine 1.16)
North Carolina: military retirement pay of a person with fewer than 20 years of service (militaryServiceYears) and no medical retirement is an ordinary pension. New York: the IRA and private pension income a person received before reaching 59 1/2 (retirementIncomeBefore59Half) draws no exclusion and is taxed as other income. Not said: the earlier reading. (New Jersey's veteran fact is read at the exemptions; Missouri's credits at the federal tax deduction.)
Interest on state, local and U.S. obligations
The state's own treatment of interest: the federally tax-exempt interest on other states' obligations (outOfStateMunicipalInterest) is added where the state taxes it, and its own (inStateMunicipalInterest) where it taxes that too; the interest on U.S. obligations (usObligationInterest, a part of ordinaryIncome) is taken out (31 U.S.C. 3124). Both change the state's income, its own income tests and its base, never the federal income total above. Each state's rule is on its page (interest). Illinois adds all of the federal 2a interest (IL-1040 line 2), so the part of taxExemptInterest not split into the two municipal parts is added too.
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). Where the caller's early dollars decide (MS), only they are taxed and the rest of that person's distributions pass the exclusion's age gate (not said: the age gate alone). The early dollars with no exception are also counted for the federal §72(t) additional tax that MO adds to the federal tax it deducts and that OK takes back out of federalTaxBeforeCredits for the federal child credit limit.
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, Arkansas's retirement exemption, which has no age test for employer plans) they count as pension income, up to the distributions not already pension or military pay; in Arkansas their early dollars still bear the additional tax on early distributions; 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.
Domicile test for the pension exclusion
From 2027, a person 60 or older who has been domiciled in the state fewer than the minimum years at the end of the year takes no pension exclusion, general or military (DE 30 Del. C. 1106(b)(3)f.4: 3 years for a person domiciled before 2027, 5 after; the Controller General's fiscal note reads the act as effective for tax years after January 1, 2027, so the 2026 rules carry no minimum and the projection schedules 3 from 2027, 4 in 2030, 5 from 2031). Applied only when the caller gives the person's domicileYears; on a joint return per spouse when the spouse's own facts are given, else to the return when every person on it fails.
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.
Working military retiree 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)
Montana (MCA 15-30-2120(3)(n), (8); Form WMRE; Form 2 Schedule I line 13): for each person whose workingMilitaryRetiree fact says they meet the residency and five-year test of (9), the lesser of 50% of their own military retirement pay and the Montana earned income on the return (wages and business profit; each spouse's form reads the return's whole wages); a survivor that share of the benefits at any income. Not said: no subtraction, the pay taxed as a pension. On the household path the fact and the pay are the filer's.
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).
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, 25% 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; the IN-112 worksheet carries the fraction kept to two places (golden round 4).
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.
Charitable increase of the standard deduction
Arizona (A.R.S. 43-1041(I)(2), taxable years after 2025): the standard deduction is increased by the taxpayer's charitable contributions (the cash gifts given, charityCash), at most $1,000 for a single person, a married person filing separately or (the statute names no cap) a head of household, and $2,000 for a married couple filing a joint return.
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 its worksheet carries the fraction to a set number of places (Maine: four, "enter 1.0000"), so does the engine (golden round 4). 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; where the caller supplies federal taxable income, the add-back is taken from the federal deduction the caller gives with it (conformity-itemizer-addbacks).
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.
Taxpayer credit base of a federal itemizer
When the caller gives the federal return's deduction and it itemized, the credit base is the federal itemized deduction less the state income tax in it (TC-40 lines 12-15) instead of the standard deduction with its age and blindness amounts.
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. Maryland (state engine 1.16): with interest on U.S. obligations the tiers test federal AGI less that interest (502SU line hh, Worksheet 13C).
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). State engine 1.16: veteran (per person) decides when given: true gives the exemption with or without military retired pay, false none.
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. Where the statute counts it among the person's own modifications (West Virginia, 11-21-12(c)(9)(ii) and (c)(1)), the U.S. obligation interest subtraction reduces the amount too (half each on a joint return).
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).
Business income deduction
The self-employment net profit (selfEmploymentIncome, the Schedule C or K-1 amount before half the self-employment tax) is deducted from the state base up to the cap ($250,000 per return, $125,000 on a separate return). The income tests read before it are unchanged (Ohio's MAGI adds the deduction back).
The federal below-the-line deductions
The amounts the federal return deducts below AGI, which a state that allows them takes as they are (26 U.S.C. 224, 225, 163(h)(4) and 170(p), the federal caps and phase-outs as the statutes print them): the Schedule 1-A qualified tips deduction (the employee tips up to the per-return cap, less the statute's step for each whole thousand dollars of modified AGI over its single or joint start; none on a separate return), the qualified overtime deduction (its cap, doubled on a joint return, the same reduction; none on a separate return), the qualified passenger vehicle loan interest deduction (its cap, less the statute's step for each thousand dollars, or part, over its start) and the non-itemizer charitable deduction (cash gifts to public charities other than donor-advised funds, up to its cap, doubled on a joint return, and the 60 percent of AGI limit). Modified AGI is the engine's federal AGI. With computeFederal the federal return's own tips, overtime and 170(p) amounts are used.
Tips, overtime, vehicle loan interest and non-itemizer charity
Where the state allows a federal below-the-line deduction (fbl_tips_cap, fbl_overtime_cap, fbl_car_loan_cap, fbl_charity_cap above 0), the federal amount (federal-bl-amounts) is subtracted from the state base, and the state's own per-person amounts are subtracted too: each person's tips up to own_tips_cap_pp and qualified overtime up to own_overtime_cap_pp (the spouse's own on a joint return with the spouse object; without it the household amount is the filer's). Where the state's base is the federal return's taxable income (computeFederal), the federal deductions are already in it and the state adds back the ones it does not allow (fbl_fti_addback). Where the subtraction is in the state's AGI (fbl_reduces_state_agi: NY), the tests on that AGI see 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).
Michigan Form 4884 Section C (pension from employment exempt from Social Security) only when the caller says the pension was not covered by Social Security
A filer 62 or older with a public pension from employment not covered by Social Security subtracts, on Form 4884 Worksheet 3.2, the public benefits plus the private ones within the limit, up to the single or joint cap. While the older spouse is under 67 the questionnaire says to compare Worksheet 3.2 with Worksheet 3.3 (Section D) and claim the larger; the engine takes the larger.
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.
The state's own itemized deduction from the federal Schedule A
When the caller hands over the federal Schedule A (POST /api/state-tax computeFederal with federalItemized on a full-year resident return; Georgia also on a part-year or nonresident return, the itemized deduction times the Form 500 Schedule 3 line 9 ratio as line 13 prorates it, 2025 in whole dollars), the state's itemized deduction is built from its lines by the state's own schedule (which taxes count and under which cap, the medical floor, the gift limit, caps and the overall limitation) and weighed against the standard deduction with any age and blindness amounts an itemizer gives up; the return takes the larger, or follows the federal choice (Oklahoma). Maine's income phase-out reduces the itemized deduction as it does the standard one. Louisiana's line 9D, Massachusetts' line 2e medical exemption and Vermont's IN-112 line 11 medical deduction are subtracted on top of the standard deduction after federal itemizing; Massachusetts' Schedule Y line 9c charitable deduction is subtracted whether or not; Wisconsin has no itemized deduction but a credit on the Schedule A items over the standard deduction (itemized-deduction-credit); Oregon's special medical subtraction for a single filer 66 or older without dependents follows the choice. A return starting from federal taxable income has the federal itemized deduction in its base already.
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, and the API with computeFederal), 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 deduction add-backs on the federal-taxable-income base only when the caller supplies federal taxable income (the planner; not the API)
When the caller also gives the federal return's deduction (the planner and computeFederal do): a federal itemizer adds back the state income tax deducted on Schedule A, at most the excess of the itemized deductions over the standard deduction (Colorado, Montana); above the income threshold Colorado adds back the federal deduction beyond the status amount, less that add-back.
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). State engine 1.16: Missouri figures it on federalTax less federalEarnedIncomeCredits (MO-1040 line 9), plus the §72(t) additional tax on the early dollars without an exception (MO-1040 line 10).
Detail record
The bases, exclusions and subtractions are recorded per person (or for the household) for the breakdown.
South Carolina 2025: retirement deduction and age 65 deduction as two lines
Engine 1.19.0, a 2025 South Carolina return: for a person 65 or older the one combined age deduction is shown as the form shows it, the retirement deduction (line p-1 / p-2, the person's own retirement income up to the 12-6-1170(A) amount less the military retirement deduction) first and the age 65 and older deduction (line q) the rest. Only the breakdown lines move; the total and the tax do not.
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.
2025 tax line rounded to the whole dollar (VA, MO, WV, DE, CA, OR, GA, ME, VT, MT, PA, MI, IL, OH, AZ, ID, UT, LA, NE, IN, MS, NC, CT, AR, MN, CO, KS, NY, NM, WI, HI, MA, AL, OK, SC, KY, DC)
Engine 1.20.0, a 2025 return in a state whose 2025 instructions say the tax line is a whole-dollar line (VA Form 760 line 16, MO-1040 lines 30Y/30S for each spouse, WV IT-140 line 8, DE PIT-RES line 24, CA Form 540 line 31, OR-40 line 20, GA Form 500 line 16; engine 1.21.0 adds ME Form 1040ME line 20 and VT IN-111 line 8 where the rate schedule gives them, MT Form 2 page 2 lines 8, 10 and 12, PA-40 line 12, MI-1040 line 17 and IL-1040 line 12, each rounded; engine 1.24.0 adds AZ Form 140 line 46, ID Form 40 line 20, UT TC-40 line 10, LA IT-540 line 11, NE Form 1040N line 15, IN IT-40 line 8 and MS Form 80-105 line 15, and OH IT 1040 line 8a with its schedule base amounts, ty25-oh-whole-dollar-tax): the rate-schedule tax is rounded to the nearest dollar, half a dollar up: since engine 1.24.0 from the exact amount (ty25-round-exact), except California and West Virginia, whose rate-schedule worksheets write the product to the cent first. Table rows are whole dollars already. The instructions' own worked examples are quoted at the marker and pinned in the printed-answer fixtures. Golden round 10 adds NC (D-400 line 15), CT (Tax Calculation Schedule line 4), AR (AR1000F line 29, and each column of filing status 4), MN (M1 line 10), CO (DR 0104 line 13 and its worksheet above the table), KS (K-40 line 8; above the table the Tax Computation Worksheet with its printed whole-dollar subtraction amounts, not the exact bracket sums), NY (IT-201 line 39 and each line of the tax computation worksheets), NM (PIT-1 line 18 and its schedule above the table) and WI (Form 1 line 12): these nine round half a dollar up from the exact amount, with no cents step (st25_dollar6), so a product whose cents are 49.73 is rounded down (CT Table B, golden round 10 CT-09). Golden round 10, group C adds HI (N-11), MA (Form 1 line 22, line 24 apart), AL (Form 40 line 17), OK (Form 511 / 511-NR), SC (SC1040 line 6, the printed schedule above the table), KY (Form 740 line 12, each status-2 column) and DC (D-40 line 20), in both the tax-table and the rate-schedule mode (ty25-whole-dollar-c).
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. (The attribution is shared with the District of Columbia's Calculation J, same-return-columns.)
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. (The attribution is shared with the District of Columbia's Calculation J, same-return-columns.)
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.
Business income above the deduction at a flat rate
The business income above the deduction, at most the taxable income, is taxed at 3%; the rest of the taxable income is taxed on the rate schedule.
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, Hawaii, Maine, Missouri, Vermont)
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). Maine's schedule (36 M.R.S. 5111, indexed by Maine Revenue Services) is printed the same way (the running sum of the rounded bases). Hawaii's HRS 235-51 (and Act 24's 2027 and 2029 tables) print whole-dollar bases too, each the exact sum of the lower brackets rounded to the dollar; so do Missouri's chart (RSMo 143.011; the MO-1040 worksheet adds the chart's base) and Vermont's rate schedules (32 V.S.A. 5822; the 2026 preliminary schedules, and the return's extra row where the tax table ends, with married filing separately on its own printed schedule). Other states' schedules print exact sums and the engine uses those.
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).
The state's tax table (23 states)
Twenty-three jurisdictions make a tax table mandatory below a threshold (Alabama, Arkansas, California, Colorado, the District of Columbia, Delaware, Hawaii, Kansas, Massachusetts, Maryland, North Dakota, New Jersey, New York, Oregon, South Carolina, Wisconsin; then Maine, where the form's instruction is to find the tax in the table, Minnesota, New Mexico, Oklahoma, Rhode Island, Vermont and West Virginia). Each printed table is the state's rate schedule applied to the row's midpoint and rounded half up to the dollar; the engine encodes each state's rule, not its rows: the row layout ("at least / less than" rows in most states, "over / not over" in Colorado, Massachusetts and New Mexico, California's and Kansas's rows that straddle the hundreds, Arkansas's wide first row, its one transition row and its rows offset by a dollar above it, Minnesota's and New Mexico's two short first rows, West Virginia's rows that start above zero, widen and then narrow twice), the midpoint (Kansas: the middle of the row's whole dollars), the threshold and condition each state's instructions print (New York's also on New York AGI, Vermont's also on federal AGI, at most its minimum tax's threshold, Massachusetts's on the income taxed at the general rate; Colorado and North Dakota full-year residents; West Virginia's table is not for a married filer filing separately, who uses Rate Schedule II), the schedule's bases (Hawaii's, Maine's, New York's, Oregon's and Vermont's printed whole-dollar bases) and the printed quirks: the first row of Maryland, the District, Minnesota, Rhode Island and Vermont prints no tax, Alabama's first two rows the midpoint tax truncated, Arkansas's upper rows come from its high-income table, and above the table Alabama and Arkansas add the top rate on the excess to the last row's tax, as their worksheets do, and New Mexico's last page adds the bracket rates on the excess to its last row's tax (the next bracket from a base rounded to the dollar). Two constants exist only in the 2025 printed tables and are used for 2025 only (the District's base for its top-rate rows and New York's joint base for its third bracket, each a dollar or a quarter off the schedule's); every other rule above is a construction rule, used for both years. Every printed 2025 row reproduces (research/data/state-tax-tables-2025.csv; Rhode Island's 2025 table is the only one it published, a file marked DRAFT). No state has published its 2026 table yet: a 2026 return is looked up in a table built by the 2025 rule from the 2026 schedule. A married filer filing separately reads the single column where the table prints them together; rules.taxTable.rule states each state's figures. Nebraska's table (paper filers only; electronic filers must use the schedule) and Connecticut's and Virginia's (optional, published only on their websites) are not mandatory: those states keep the rate schedule on the exact amount.
The schedule a tax table is built from
The status's brackets (a separate filer on the single column where the table prints it so), in the table's own bases (exact sums; Hawaii the exact sum of the lower brackets rounded to the dollar; New York and Oregon the running sum of the rounded bases), Arkansas's high-income table above its threshold, and for 2025 only the printed tables' own bases where they differ from the schedule's (the District's top-rate rows, New York's joint third bracket).
The tax table in place of the schedule
Where the request asks for the table (the API's default for a full-year resident, part-year resident or nonresident return of tax year 2025 or 2026 without a projection; taxTable false opts out) and the state has one, the bracket tax is the printed amount of the row the form's line falls in (Massachusetts: line 21, the income taxed at the general rate; its long-term gains are multiplied), or above an Alabama or Arkansas table the worksheet built on its last row; between the threshold and the table's end the schedule. Before the add-ons and the credits, which read it as they read the schedule. Arkansas's two columns of a married couple filing separately on one return, Delaware's combined separate columns and Hawaii's alternative gains tax look their amounts up the same way. Every C caller that does not ask (the planner, the optimizers) keeps the schedule on the exact amount.
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; where the form says so (Vermont IN-111 line 8) the U.S. obligation interest is taken out of that total first.
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).
Separately on the same return: the deduction divided between the columns joint returns with each spouse's own amounts given
On a joint return with each spouse's own amounts, each spouse's own state AGI is a column (the items with no owner half each), the return's deduction is divided between the columns as the couple wishes — the engine gives it to the larger column until the two are equal and then halves the rest, the lowest tax on a schedule whose rates rise with income — and each column is taxed on the schedule (or the tax table). The columns' sum replaces the schedule tax when lower; the credits read the combined return. Without the spouse's amounts the joint return is figured. Engine 1.24.0 (golden round 10, DC Calculation J with the tax tables): a table row prints one amount for every income in it, so the lowest tax can put one column at the top of a row and give the rest to the other; each column's table rows inside its range are tried and the lowest pair kept (on a 2025 return each column's line h in whole dollars).
2025 Ohio IT 1040 lines 8a and 8b in whole dollars
Engine 1.24.0, a 2025 Ohio return: line 8a, the schedule's tax with its printed base amounts (the bracket-cliff step), and line 8b, the business income tax, are each rounded to the nearest dollar from the exact amount, half a dollar up; line 8c is their sum. The general tax-line rounding (ty25-whole-dollar-tax) is held back for Ohio until the base amounts are added. 2026 answers are unchanged.
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. (OK: the federal limit is Form 1040 line 18, so the §72(t) additional tax in federalTaxBeforeCredits comes back out.)
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). Kentucky (state engine 1.16): the family size credit tests federal AGI plus the non-Kentucky municipal interest (modified gross income). West Virginia (state engine 1.20.1): the family tax credit tests modified federal AGI (Schedule FTC-1 line 4): federal AGI plus the increasing modifications (the other states' municipal interest) plus the federally tax-exempt interest not already among them, so its own municipal interest counts too.
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.
Charitable contribution credit
Vermont (32 V.S.A. 5822(d)(3), IN-111 lines 11-13): a nonrefundable credit of 5% of the contributions, at most $20,000 of them, whether or not the filer itemizes; the engine reads the cash gifts given (charityCash). It comes off the tax before a part-year return's income adjustment.
Itemized deduction credit
Wisconsin (Form 1 line 13, Schedule 1): a nonrefundable credit of 5% of the medical expenses, interest and gifts on the federal Schedule A over the Wisconsin standard deduction, itemizer or not, when the request carries the federal Schedule A (state-itemized figures it); the 67+ retirement subtraction forfeits it with the other credits.
Wisconsin: the 67+ subtraction forfeits every credit
A return that claims Wisconsin's 67+ retirement income subtraction (Wis. Stat. 71.05(6)(b)54m., 2025 Acts 15 and 174) takes no credit that year: the school property tax credit and the married couple credit are dropped. The elections step weighs the return without the subtraction (and with the credits) against it and keeps the lower tax.
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). Engine 1.19.0: a 2025 Minnesota return reads Schedule M1MA's Table for Line 8 where the form sends it there (line 6 below the Part 2 amount), none below the form's two qualifying amounts, and the formula (Part 2) above.
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. The phase-out income is modified AGI: where the state says so (Utah 59-10-1019(1)(e)) it adds the federally tax-exempt interest (federal line 2a).
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. State engine 1.16: the eligibility income adds back the nontaxable interest of Schedule A lines 6 and 7 (inStateMunicipalInterest and usObligationInterest) when the interest split gives it.
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, as Form 1040 line 27a has it: the EIC Table's whole-dollar credit (IRC 32(f): the credit at the midpoint of each of the table's narrow income brackets), at earned income and, when the income total differs and is at least the phase-out start, at the income total, the smaller of the two. Each table row is the credit rate on income up to the maximum, less the phase-out rate on the 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 from the completed phase-out amount; 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. A tax-year-2025 return (QCST_WITH_TY2025) reads the 2025 IRC 32 amounts (st_fed_eic_base).
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 and the age deduction (Form 760 line 9; before 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. Within the table's limits the table is the tax (line 27: "If you qualify to use a Low-Income Tax Table, enter zero"), unless the filer gives up an exclusion or itemizes (the AR3 itemized deduction above the standard deduction: "If you itemize your deductions, you must use the Regular Income Tax Table"): then 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).
Disability pay before the plan's minimum retirement age is earned income
For the federal earned income credit that state credits read, and the child tax credit's earned income, disability pay received before the plan's minimum retirement age is earned income (Form 1040 line 1h; IRS Pub. 525 and Pub. 596): each person's disabilityIncome while under that person's planMinimumRetirementAge, under 65 when it is not given (inputsNotSupplied shows the range).
The state credits' earned income includes that disability pay
The refundable and nonrefundable earned income credits figured from the federal credit (for example Colorado, New York, California, the District of Columbia, Wisconsin, Ohio, Missouri, Virginia, Maryland) and Minnesota's working family credit count the disability pay of the step above as earned income; it is not investment income.
Virginia: no low-income or earned income credit with the age deduction or an aged / blind exemption
VA §58.1-339.8(D): when anyone on the return claims the age deduction or the additional exemption for the blind or aged, none of the subsection B credits is allowed — the low-income credit, the nonrefundable and the refundable share (20%) of the federal EIC (va-credit-election weighs forgoing them). The low-income credit tests the family's Virginia AGI after the subtractions (Social Security, military benefits, disability income) against the guideline for the family's size; it is not calculated on a separate return, whose family VAGI includes the other spouse's.
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.
2025 Utah TC-40 line 10 and the credit worksheets in whole dollars
Engine 1.24.0, a 2025 Utah return: line 10 is the tax on all of line 9 (the Social Security the AH credit offsets included) and the Social Security Benefits Credit is its own worksheet's lines 4, 12 and 13, each in whole dollars; the taxpayer tax credit's lines 16 and 19, the Retirement Credit worksheet line 9, the Military Retirement Credit worksheet line 2 for each person (one worksheet per person, the spouse's own pay when the request gives it) and the Child Tax Credit worksheet line 10 are each rounded to the nearest dollar from the exact amount. 2026 answers are unchanged.
After credits: county tax, surcharges and surtaxes
Local net-profits taxes on the business's own profit
A local tax on net profits takes the Schedule C profit itself, not the profit less half the self-employment tax: Pennsylvania's local earned income tax, Philadelphia's net profits tax, the Ohio municipal net profit, Kentucky's occupational taxes, the Kansas City and St. Louis earnings taxes and Wilmington's; each person's half is added back. A Michigan city adds it back as income (Detroit Form 5118 line 26). An Ohio school district's earned-income base reads the federal net earnings from self-employment (Schedule SE line 4a, SD 100 line 30).
2025 early-distribution taxes from whole-dollar lines (CA per spouse; NE, VT, WI, AR from the federal Schedule 2 line 8 tax; OR, MO federal tax)
Golden round 11: on a 2025 whole-dollar return the state's tax on early distributions is figured from whole-dollar lines. California: each spouse files his or her own FTB 3805P, each form's tax is rounded to the dollar, and line 63 is the combined tax. Nebraska Form 1040N line 16b, Vermont IN-119, Wisconsin Form 1 line 25 and Arkansas line 32 start from the federal Schedule 2 line 8 tax entered in whole dollars, as does the federal tax Oregon and Missouri deduct.
Vermont Child Care Contribution (IN-111 line 21) only when the caller gives self-employment income with computeFederal
A full-year Vermont resident with self-employment income (computeFederal) owes the Child Care Contribution, a percentage of each person's federal Schedule SE line 6 (none under the SE filing floor), on IN-111 line 21, in Total Vermont Taxes. It is not income tax: it is in totalTax and netTax and listed in otherReturnTaxes, and tax stays the income tax. Whole dollars on the 2025 return. Self-employment income earned outside Vermont (worksheet line 2) is taken as none.
2025 Oregon part-year and nonresident tax on the OR-40-N/P charts only when the caller gives a part-year or nonresident residency
Golden round 11: Forms OR-40-N (line 46) and OR-40-P (line 44) figure the tax on the 2025 OR-40-N/P tax rate charts, not on the resident OR-40's tables and its chart for higher incomes: Chart S (single, married filing separately) and Chart J (joint, head of household, qualifying surviving spouse), each bracket's printed base the previous base plus that bracket's tax rounded to the dollar. OR-40-P line 45 multiplies the whole-dollar line 44 by the Oregon percentage.
2025 refundable credit lines in whole dollars (ME, VT, MT, VA, OR, MO, DE, GA, WV, CA, PA, MI, IL, OH, AZ, ID, UT, LA, NE, IN, MS, NC, CT, AR, MN, CO, KS, NY, NM, WI)
Engine 1.21.0, a 2025 return of a whole-dollar state (ty25-whole-dollar-lines): each refundable credit line is entered in whole dollars (ME earned income credit worksheet line 3, VT IN-112 Part II, OR Kids Credit, VA Form 760 line 23's refundable share of the federal EIC, ...); a line that rounds to nothing drops out of refundableCredits. Golden round 10 adds NC, CT, AR, MN, CO, KS, NY, NM and WI (CT EITC, CO, MN, NM, NY and NYC credit lines).
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 the net capital gain: the long-term gain, and in Maryland (engine 1.24.0, golden round 10) the short-term gain too, as Form 502CG line 1 (Form 502 line 1c, the federal Form 1040 line 7 gain) reads it.
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. The NYC tax is Tax Law §1304(a)'s schedule with its printed whole-dollar base amounts, plus the §1304-B additional tax on it.
New York City's tax table
A full-year New York City resident whose NYC taxable income is below the table's threshold looks the NYC tax up in the NYC tax table (IT-201 line 47a; its own short first rows, then fifty-dollar rows), the printed schedule on the row's midpoint rounded to the dollar; every printed 2025 row reproduces.
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; PA's Working Pennsylvanians Tax Credit, a tenth of the federal EIC, from 2025), New York's Empire State child credit (IT-213; state engine 1.16), the refundable child and dependent credits figured from the dependents' ages (MA Form 1 line 46, ME DETC, NJ line 65, NM PIT-RC line 25, OR Kids Credit, VT IN-112, CO DR 0104CN with 2025's Family Affordability Tax Credit, IL Schedule IL-E/EITC Step 5, MD Worksheet 21C, CA's young child tax credit, and MN's child tax credit with the Working Family Credit on Schedule M1CWFC), 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). Golden round 3: Hawaii's food/excise bands are "under" their upper amounts, read on the N-11's whole-dollar AGI. Engine 1.19.0 (tax year 2025, the printed charts): the MO-PTS Property Tax Credit Chart, Oklahoma's 511-EIC 2020 EIC Table and Colorado's TABOR State Sales Tax Refund (DR 0104 line 38).
Refundable credits a part-year return keeps only when the caller gives a part-year or nonresident residency
Golden round 3 (part-year audit, HI-py-2): Hawaii's food/excise tax credit (Form N-311, claimed on N-15) for a part-year resident "physically present in Hawaii for more than nine months" (the resident days taken as the presence: 274 or more), on the whole year's federal AGI; every other refundable credit is left out of a part-year or nonresident return.
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 credits and the low-income credits are left out, except Massachusetts' No Tax Status and Limited Income Credit and Pennsylvania's Tax Forgiveness, tested on the whole year's income (golden round 3); each state's form rounding of its ratios and lines (round 4: VA 760PY whole dollars, 50 cents down, each exemption on its own; ID 39NR line 22h a whole percent); a nonresident's retirement income is refused (4 U.S.C. §114); where the request asks for the tax table, the state's part-year or nonresident form's table (Wisconsin's Form 1NPR line 38 table included; a nonresident's since engine 1.23.0, Maryland's Form 505NR table only below its own, lower threshold; New Jersey's NJ-1040NR, whose table is the filer's choice, on the schedule), except Oregon (OR-40-P / OR-40-N: the tax rate charts) and West Virginia (Schedule A: the rate schedule).
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; the state tax from the 505NR table only below its own threshold, residency-md-nr-table); VA's 763 (taxable income × the allocation percentage, then the schedule). Golden round 3: WI's Form 1NPR on line 31, the federal column (federal AGI with the taxable Social Security; the standard deduction read there), x line 30 / line 31, the 67+ subtraction's maximum prorated by Schedule M line 50 and no tax when line 30 is zero or less; DE's pension ratio to four places; OR-40-P's exemption credit x the percentage in whole dollars and the retirement income credit on the Oregon column, not prorated; ND's long-term gain exclusion figured on at most the North Dakota gain; SC / ND leave the period's Social Security out of the state column, UT keeps it in both, NE in the numerator; MN no tax under its filing requirement, IA none under IA 126 line 27's minimum of Iowa-source income; HI's ratio cut at the third place.
Maryland nonresident: the Form 505NR table's own threshold only when the caller gives a part-year or nonresident residency
Engine 1.23.0, a Maryland nonresident return (Form 505 / 505NR) where the request asks for the tax table: Form 505NR line 2 looks the whole year's taxable net income (line 1, Form 505 line 31) up in the nonresident booklet's table, whose rows are the resident table's but which stops at half the resident Form 502 table's threshold; from there the Tax Computation Worksheet schedules, the rate schedule on the exact amount. The state tax is then x the line 15 nonresident factor (residency-r). A part-year resident files Form 502 and keeps its table.
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. Golden round 3: MD's Worksheet 13A pension exclusion on the whole year, x months / 12, fixed; GA Schedule 3's earned portion (the lesser of the earned income and the earned maximum) and the rest each x its own 4-place ratio; AL 40NR's chart read at the whole year's column B AGI and its federal tax deduction x line 10; DC's and ID's federal senior deduction prorated (days; ID Worksheet 1-A Part IV); ID's food tax credit (months x the monthly amount, not refunded); OR-40-N's exemption credit in whole dollars; VA 760PY's prorated amounts in whole dollars; PA Schedule SP's eligibility income adds the income received outside Pennsylvania.
2025 part-year / nonresident prorated exemption allowance in whole dollars (MI, IL) only when the caller gives a part-year or nonresident residency
Engine 1.21.1, a 2025 part-year or nonresident return in Michigan or Illinois: the prorated exemption allowance (MI Schedule NR line 19, line 15 x the line 18 percentage, or Worksheet 6 when one spouse is a full-year resident; IL Schedule NR line 50, line 49 x the line 48 decimal) is rounded to the cent and then to the nearest dollar, half a dollar up, like every other line of the two whole-dollar returns (ty25-whole-dollar-tax). The engine's own prorated total (per-spouse factors included) is rounded and the difference carried on the deduction slot the filing status reads, where both states carry the personal amount. 2026 answers are unchanged.
2025 county tax line in whole dollars (IN)
Engine 1.24.0, a 2025 return of a whole-dollar state with a county tax on the state taxable income (Indiana: Schedule CT-40 line 3, the county rate x line 1, IT-40 line 9): the county tax is rounded to the nearest dollar from the exact amount, half a dollar up (st25_line). 2026 answers are unchanged.
2025 Ohio SD 100 lines in whole dollars
Engine 1.24.0, a 2025 Ohio school district return: line 22 (a part-year resident's portion of line 5, line 5 x the four-place residency factor) and line 25, the tax (line 23 x the district rate), are each rounded to the nearest dollar from the exact amount; the senior citizen credit follows. 2026 answers are unchanged.
2025 part-year / nonresident prorated deduction and exemption lines in whole dollars (ID, AZ, MS, IN) only when the caller gives a part-year or nonresident residency
Engine 1.24.0, a 2025 part-year or nonresident return taxed on the state's own income (method D) in Idaho, Arizona, Mississippi or Indiana: the prorated lines are rounded to the nearest dollar from the exact amount as each form writes them: ID Form 43 line 39 (the deduction x the line 38 percentage) and the Worksheet 1-A line, AZ Form 140PY line 51 (the exemptions x the Arizona income ratio; the standard deduction is not prorated) and Form 140NR's prorated deduction, MS Form 80-205 lines 14b and 15b (two lines), IN Schedule D line 9 (one line for every exemption). The engine's own prorated amounts are rounded and the difference carried on the deduction slot the filing status reads. 2026 answers are unchanged.
2025 part-year / nonresident prorated deduction and exemption lines (HI, MA, AL, DC, SC; MD to the cent) only when the caller gives a part-year or nonresident residency
Golden round r10, group C (unreleased), a 2025 part-year or nonresident return taxed on the state's own income with the form's prorated items: each prorated line as the form writes it — HI N-15 line 40b (the deduction x the line 37 ratio) and line 42b (the exemptions); MA 1-NR/PY line 22 (all exemptions x line 14g, one line); AL 40NR the deduction, the personal exemption and the dependents' lines apart; DC Calculation C (the standard deduction x the days); SC Schedule NR line 47; MD Form 502 lines 17 and 19 to the cent. The engine's own prorated lines are rounded and the difference carried on the deduction slot the filing status reads, kept only when the taxable income moves by exactly that much. 2026 answers are unchanged.
Conventions: rounding and later years
2025 whole-dollar returns, line by line (ME, VT, MT, VA, OR, MO, DE, GA, WV, CA, PA, MI, IL, OH, AZ, ID, UT, LA, NE, IN, MS, NC, CT, AR, MN, CO, KS, NY, NM, WI, HI, MA, AL, OK, SC, KY, DC); RI, MD, ND and IA lines to the cent
Engine 1.21.0, a 2025 return in a state whose 2025 instructions say every amount on the return is a whole-dollar amount (ME "Use whole dollar amounts", VT "Round entries to the nearest whole dollar", MT Form 2 "00" cents, VA, OR, MO, DE, GA, WV, CA, PA, MI, IL): a worksheet's or a credit's product is rounded where the form writes it (half a dollar up from the exact amount since engine 1.24.0, ty25-round-exact; California and West Virginia to the cent first): ME standard/itemized deduction and exemption phase-out line 7, pension deduction, property tax fairness credit lines; VT Social Security / military / non-covered pension partial exemptions, the IN-153 cap on federal taxable income, the minimum tax, the IN-119 early-distribution tax, the charitable credit; MT Schedule II, 2EC and the itemized add-back; VA Form 763 lines 17-18 and the itemized total; OR-40-N line 42 (the deduction plus the federal tax subtraction prorated as one product); MO-1040 line 33 per spouse and the federal tax deduction; GA's part-year retirement exclusion and Schedule 3 line 13 of a separate return; WV Schedule M line 34; CA FTB 3805P line 4 and Form 540NR lines 35/37/39; PA Schedule SP line 16; MI-1040CR lines 12, 34 and 38/41, Worksheet 5 and Form 4884 Worksheet 3.3 line 4; IL Schedule ICR line 4g and the child tax credit on the rounded IL EITC. Engine 1.24.0 adds OH (Schedule of Credits line 12, the joint filing credit; IT NRC line 20; line 13, the share of the federal EIC), UT (TC-40 lines 16 and 19, the AH, AJ, code 18 and AT credit worksheets: ty25-ut-whole-dollar-credits), AZ (the reduced dependent tax credit), ID (Form 43 line 63, the part-year food tax credit), IN (CT-40 line 3, the county tax: ty25-whole-dollar-local) and the prorated deduction and exemption lines of AZ, ID, MS and IN part-year and nonresident returns (ty25-py-whole-lines); LA, NE and MS lines the engine computes are the tax line and the ratio products. The eight states of engine 1.24.0 round from the exact amount, with no cent step (st25_dollar6). Golden round 10 adds NC, CT, AR, MN, CO, KS, NY, NM and WI, rounded half a dollar up from the exact amount (st25_dollar6): NC D-400 line 14 (Schedule PN: line 12b x the line 24 decimal) and line 15; CT Tax Calculation Schedule line 9 (line 7 x the Table E decimal) and CT-1040NR/PY line 10; AR1000NR line 38D and AR line 32 (the early-distribution tax); MN M1NR line 32 and Worksheet A for line 4 steps 3, 5 and 8; CO DR 0104PN line 36; KS K-40 line 10; NY IT-203 line 46, the NYC and Yonkers lines and the household and school credits; NM PIT-B line 14 and the low- and middle-income exemption worksheet line 5; WI Form 1NPR line 39, the married couple credit and the line 25 early-distribution tax. RI-1040 lines keep the cents ("must include cents"). The sources are quoted at st25_whole_lines and st25_cents_lines; the printed-answer fixtures pin the forms' examples. Golden round 10, group C adds HI, MA, AL, OK, SC, KY and DC to the whole-dollar returns and MD to the cents returns ("State calculations are rounded to the nearest cent"); their own lines are at ty25-whole-dollar-c.
2025 whole-dollar lines: one rounding, from the exact amount (CA and WV to the cent first)
Engine 1.24.0 (golden round 10): every whole-dollar line of a 2025 return (ty25-whole-dollar-tax, ty25-whole-dollar-lines, ty25-whole-dollar-c and the state lines that cite them) is rounded by one function (st25_dollar6) on the one list of 2025 whole-dollar returns: half a dollar up from the exact amount, with no step to the cent first, as each state's form says (Virginia: "Amounts less than 50 cents should be rounded down while all amounts of 50 cents - 99 cents should be rounded up"). An amount whose cents are at least 49.5 but under 50 is rounded down: a Connecticut Table B product with 49.73 cents is entered a dollar lower than engines 1.20.0-1.23.0 entered it (they rounded it to the cent first, golden round 10 CT-09). California and West Virginia keep the step to the cent: their rate-schedule worksheets write the product to the cent before the total is rounded (California's Step 4, "round the amount from Step 3 to two decimals"; West Virginia's Rate Schedule example). 2026 answers are unchanged.
2025 whole-dollar returns: the amounts you enter are whole dollars too (37 jurisdictions); ND and IA lines to the cent
Golden round 11: on a 2025 return in one of the 37 whole-dollar jurisdictions every amount the form makes you enter is a whole dollar, not only the lines it computes: each income amount of the request (one entry of the form: a person's wages, the household's interest, a part-year return's state-source amounts), each federal-return line the state return copies (with computeFederal: the taxable Social Security, the federal tax lines, Form 1040 lines 12e and 13b one by one, so Montana's line 3 is the entered federal AGI less each entered deduction line) and a credit's facts (the property tax paid) are entered rounded, half a dollar up, and a figure the form reads from its own charts by income (a standard deduction or child deduction table, an exemption tier, a tax-table row) is read on the entered amount. The request is validated on the amounts as sent (a negative cent is still refused); input shows the amounts as entered and yearNotes says so. North Dakota's and Iowa's 2025 lines are written to the cent, as Rhode Island's and Maryland's (Iowa's whole-dollar rounding is optional). 2026 answers are unchanged.
2025 whole-dollar lines of HI, MA, AL, OK, SC, KY, DC; MD to the cent; MT's printed tax table
Golden round r10, group C (unreleased): on a 2025 return the lines of these states' forms are entered as the forms say. Whole dollars (every line of these returns, and of OR's and MT's, rounded once from the exact amount to the nearest dollar, half up, not to the cent first): HI the Tax on Capital Gains Worksheet lines; MA Form 1 line 22 (the tax on the line 21 income) and line 24 (the long-term gains) apart, line 23b (the short-term gains), line 28b (the surtax) and the Limited Income Credit worksheet's limit line; OK Schedule 511-F line 7 (the child credit x Oklahoma AGI / federal AGI) and the earned income credit; SC1040 line 12 (two wage earner credit); KY 740-NP line 18 (the personal credits x the line 7 percentage) and line 21 (the family size credit) on status 2 too; DC Calculation J line h per column; OR-40-P line 45 (the tax x the Oregon percentage) and the retirement income credit; MT Schedule II lines 19 and 24, each product rounded once (not to the cent first and then to the dollar). MD: the local tax (line 28), the local credits and Form 505's lines to the cent. MT Form 2 line 12 is the instructions' Ordinary Income Tax Table, which the filer is told to use: the first rate below the first bracket's top, else the second rate on the whole income less the table's whole-dollar amount (the statute's split subtracts the same differential with its cents; the printed table drops them). 2026 answers are unchanged. Audited and left in cents: RI, NJ and IA (optional rounding), ND (no rounding instruction).
Rounding
The engine rounds where the return does. On a 2025 return, the states whose forms are whole-dollar returns are rounded line by line as the form says (ty25-whole-dollar-tax, ty25-whole-dollar-lines, ty25-whole-dollar-c): VA, MO, WV, DE, GA, OR, MT, VT, ME, PA, MI, IL, CA; OH, AZ, ID, UT, LA, NE, IN, MS; NC, CT, AR, MN, CO, KS, NY, NM, WI; HI, MA, AL, OK, SC, KY, DC; RI, MD, ND and IA lines are kept to the cent (ND and IA since golden round 11). Each line is rounded once, as the form enters it, half a dollar up from the exact amount, except the California and West Virginia rate-schedule tax, which their worksheets write to the cent first (ty25-round-exact); since golden round 11 the amounts the form makes you enter (the request's amounts, the federal lines the state return copies) are entered in whole dollars too (ty25-whole-entries). A 2026 answer keeps the cents. Where a state's instructions look the tax up in a table of income bands, the table is used when the request asks for it (the default on a 2025 return): full-year returns, part-year returns since engine 1.22.0 and nonresident returns since 1.23.0. Elsewhere brackets, phase-outs and credits are computed in double precision. South Carolina rounds the reduction of its income-adjusted deduction down to a whole ten dollars, and the engine does the same. 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). 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.
The federal earned income credit of a projected year
The federal credit the state's shares of it read (a percentage of the federal earned income credit for the same taxable year, refundable or not) is the configuration's year's: a projection in indexing "law" records its year and factor (fed_eic_year, fed_eic_factor), and the federal amounts (maximum credit, phase-out starts, investment-income limit) then move as Maryland's eic_* amounts move, being the same federal amounts by reference: tax year 2027 the figures Rev. Proc. 2026-35 prints, later years the 2026 amounts at the factor with the federal rounding. The rules year, indexing "inflation" and a tax-year-2025 return read the rules year's credit. State engine 1.28.0.
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 |
interest_addition | Tax-exempt interest the state adds | Interest on state, local and U.S. obligations |
us_obligation_subtraction | U.S. obligation interest subtracted | Interest on state, local and U.S. obligations |
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 |
fbl_tips | Federal tips deduction the state allows (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
fbl_overtime | Federal overtime deduction the state allows (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
fbl_car_loan | Federal vehicle loan interest deduction the state allows (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
fbl_charity | Federal non-itemizer charitable deduction the state allows (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
own_tips | The state's own tips exclusion (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
own_overtime | The state's own overtime deduction (part of the other subtractions) | Tips, overtime, vehicle loan interest and non-itemizer charity |
fbl_addback | Federal below-the-line deductions added back to federal taxable income (the state does not allow them) | Tips, overtime, vehicle loan interest and non-itemizer charity |
business_income_deduction | Business income deducted (part of the other subtractions) | Business income deduction |
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 |
business_income_tax | Tax on business income above the deduction | Business income above the deduction at a flat 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: DE filing status 4, KY filing status 2) |
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:8483): 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. |
fed_eic_factor | The cumulative CPI factor of that projection (fed_eic_year after 2027: the federal EIC amounts at that factor, the federal rounding; 2027: Rev. Proc. 2026-35's); 0 = the rules year's (state engine 1.28.0) | Not an amount: the cumulative CPI factor a projection in indexing "law" records with fed_eic_year (state engine 1.28.0), from which the federal earned income credit the state's shares read is figured; 0 in every rules-year configuration. |
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. |
mil_working_retiree_pct | Working military retiree subtraction: a person who meets the residency and five-year test (workingMilitaryRetiree) subtracts the lesser of this share of their own military pay and the earned income on the return; a survivor this share at any income (MT MCA 15-30-2120(3)(n), (8); Form WMRE; state engine 1.26) | 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. |
business_income_rate | The flat rate on business income above the business income deduction, at most the state income tax base (OH IT 1040 line 8b) | a rate (OH R.C. 5747.02(A)(4), 3% on business income above the deduction): rates stay the rules year's |
charity_credit_rate | Nonrefundable charitable contribution credit: this share of the cash gifts (VT 32 V.S.A. 5822(d)(3), IN-111 lines 11-13; charityCash; state engine 1.16.6); 0 = none | A share. |
item_med_floor | The state's own medical floor, a fraction of AGI (0 = the federal line 4) | A share of AGI. |
item_limit_rate1 | Overall limitation: the rate on AGI over the first threshold | A rate. |
item_limit_rate2 | Overall limitation: the rate on AGI over the second threshold | A rate. |
item_limit_max_pct | Overall limitation: at most this share of the deductions other than medical | A share. |
item_charity_pct | The share of AGI the gifts may reach on the state's schedule (0 = 60%; CA 50%) | A share of AGI. |
item_credit_rate | Itemized deduction credit: the rate on the Schedule A items over the standard deduction (WI Schedule 1: 5%) | A rate. |
What the engine does not calculate
- Itemized deductions when the request does not carry the federal return's Schedule A (the return then takes the standard deduction), and the itemized amounts and rules that input does not carry, which each state page lists.
- Credits a state page does not list.
- Dependents: refundable child tax credits and other refundable dependent credits a state page does not list, and dependent credits that need expenses or facts the input does not carry (adoption, custody, certification, a child's schooling); each state page lists its own. Child and dependent care credits, which can apply with no dependent (the care of a spouse who cannot care for themselves), and education credits, which can be for the filer's own schooling, are not part of this item: each state page lists them apart.
- Blindness and disability: low-income or wage-tested disability credits and rules that need facts the inputs do not carry; each state page names its own.
- Refundable credits: programs claimed on their own application or claim form rather than with the return's credits (New Jersey's ANCHOR, Senior Freeze and Stay NJ, Pennsylvania's Property Tax/Rent Rebate, Minnesota's homeowner Homestead Credit Refund, Vermont's property tax credit, Kansas's homestead and senior property tax refunds, Maryland's homeowners' and renters' tax credits, Colorado's property tax/rent/heat rebate, Utah's circuit breaker, Arizona's property tax credit, Michigan's home heating credit), and each program's rules for property that is not the filer's main home all year (part-year ownership, shared or business use, mobile-home lots, nursing homes); and the income of household members outside the return, which is not an input (a program's household income is the return's own).
- Other-state credits: the credits for tax paid to other states (a resident's or part-year resident's credit for income tax paid to another state, country or locality, each state's own formula) are not calculated.
- Part-year and nonresident returns: a nonresident servicemember's military pay, nonresident aliens, installment-sale elections, reciprocity agreements between states (the caller leaves the wages a reciprocal agreement exempts out of stateIncome), the earned income and low-income credits on these returns, the dependent credits (dependents are refused with residency), Virginia's Filing Status 4 on the 760PY, Hawaii's joint-return election taxing the combined income for the part-year resident's period, the credit for tax paid to the other state on a joint resident return, and a couple's local returns (localities are refused with residency.spouse); the pairs a state's instructions do not address, and the joint or separate returns whose computation is the state's own, are listed on its page and refused. For a part-year resident's local taxes: a part-year New York City resident's NYC school tax credits and NYC earned income credit, and the part-year rules of Philadelphia, Ohio municipalities and traditional-base school districts, Michigan cities (Detroit Form 5120), Kentucky, Kansas City, St. Louis, Wilmington, Portland Metro and Multnomah County, a part-year Yonkers resident's nonresident earnings tax, an Indiana nonresident's county tax and Maryland's Form 515: the API refuses the inputs these need.
- State alternative minimum taxes.
- Local income taxes outside the engine's locality registry: per-worker head taxes and employer payroll taxes, other Kentucky occupational taxes, Ohio's grandfathered Wyoming and Indian Hill, and a resident's credit for local tax paid elsewhere other than Pennsylvania's Act 32 credit (
otherLocalTaxCredittakes the amount). - Business income rules: pass-through entity taxes, net operating losses, depreciation differences and other state additions and subtractions outside the income types listed on the API reference.
- Optional tax tables (Nebraska's for paper filers only, Connecticut's and Virginia's published only on their websites): the rate schedule is applied to the exact amount instead, which those filers may also use.
- Withholding, estimated payments, penalties and interest: the engine computes the year's liability only.
- Out-year rules that are not yet law: later years reuse this year's rules with indexed dollar amounts (see Later years).
What it does not calculate for one jurisdiction is listed on that jurisdiction's page, under "What the engine does not calculate".