State tax docs / Couples and income types

Couples and income types

How the engine treats a married couple, and which kinds of income it tells apart. Request fields are on the API reference; this page explains the model behind them.

Income types

The request's income fields are separate amounts that do not overlap: each dollar goes in exactly one field. Three further fields describe part of another rather than adding income: earlyDistributions (part of iraDistributions and employerPlanDistributions), socialSecurityGross (which includes socialSecurity) and railroadRetirementTier1 (part of socialSecurityGross). iraBasis is not income at all: it is the after-tax contributions not yet recovered, which a state that taxes an early distribution only above them reads.

API field	What goes in it	Why it is separate
`wages`	W-2 wages and net self-employment income	Some states treat earned income differently from other income.
`iraDistributions`	Traditional IRA distributions, excluding conversions	Several states exclude pensions but not IRAs, or gate IRA dollars by age.
`employerPlanDistributions`	401(k), 403(b) and 457(b) distributions, excluding conversions	Taxed like IRA money except where a pension rule covers employer plans (Maryland, Rhode Island, Arkansas).
`pensionPrivate`	Private-employer pension or annuity	Pension-only exclusions (for example Maryland and Rhode Island) apply to it.
`pensionPublic`	Government pension: civil service, state, municipal, teacher	Several states exempt it fully or up to a cap.
`pensionMilitary`	Military retirement pay	Many states exempt it on terms of their own.
`rothConversion`	Traditional-to-Roth conversion amount	States differ on whether a conversion draws the retirement exclusion.
`shortTermGains`	Net short-term capital gain	Ordinary income almost everywhere; exempt where a state exempts all gains.
`capitalGains`	Net long-term capital gain	Inclusion ratios, flat exclusions and own rates vary by state.
`socialSecurity`	Federally taxable Social Security	The base the state rules start from.
`socialSecurityGross`	Gross benefits (Social Security and Railroad Retirement Tier 1)	Connecticut's 25% cap and Maine's and Maryland's pension offsets use gross benefits.
`railroadRetirementTier2`	Railroad Retirement Tier 2 and supplemental annuities	No state taxes them (45 U.S.C. 231m); some count them against a retirement cap.
`qualifiedDividends`	Qualified dividends	North Dakota excludes part of them; Georgia and Delaware pool them with retirement income.
`ordinaryIncome`	Everything else ordinary: interest, non-qualified dividends and so on

Couples filing jointly

Without a spouse object, the person-level fields are household totals and one household age applies to every age test: the behaviour of every existing integration. With a spouse object, the top-level person-level fields (wages, iraDistributions, the three pension fields and rothConversion) are the primary filer's own amounts and spouse.* are the spouse's own amounts and age. ordinaryIncome, the gains and Social Security stay household totals, which the engine splits equally between the spouses, except that Social Security is divided by spouse.socialSecurityGross (the spouse's own gross benefits) when it is given. If spouse.age is left out, the spouse is taken to be the primary filer's age: each spouse's own income is still tested against their own cap, at that shared age.

With both ages known the engine evaluates every age-conditioned rule per person where the state applies it per person: retirement exclusions and their age tiers, senior subtractions and credits, age-gated Social Security treatment, conversion age gates and military retirement rules. Where a retirement exclusion is per taxpayer, each spouse's own dollars draw only that spouse's cap, so one spouse's large IRA withdrawal does not absorb both caps (per-taxpayer caps with a declared split since the first release: AL, AR, DE, LA, MO, OK, SC). Where the state applies one cap per joint return (MI, NJ, WI), the age test is met by either spouse (or, in the pooled-if-both case, per taxpayer until both qualify). Each state page says which applies.

The response's perPerson array reports, for each spouse, the age the rules used and every amount excluded with the rule that excluded it, so a result can be checked person by person. Every response carries it: a single filer, or a couple sent without spouse, gets one entry (primary, or household on a joint return).

Engine inputs

For library users, the engine's own input structure, as its dump tool reports it:

Engine input	Meaning
`other_ordinary`	Ordinary income that is not a retirement distribution, conversion or Social Security
`retirement_distributions`	Pension, annuity and IRA/401(k) distributions, including the pension subsets below
`pension_income`	Pension/annuity-sourced part of retirement_distributions (public and private)
`pension_public`	Public or employer-funded pension part of pension_income
`roth_conversion`	Traditional-to-Roth conversion amount
`ss_income`	Federally taxable Social Security
`ss_gross`	Gross Social Security received (0 or less = unknown)
`capital_gains`	Net long-term capital gain
`short_term_gains`	Net short-term capital gain included in other_ordinary
`age`	Filer's age (the household age for MFJ)
`federal_tax`	Federal income tax excluding NIIT (below 0 = unknown)
`federal_niit`	Federal net investment income tax (below 0 = unknown)
`fed_taxable_ordinary`	Federal ordinary taxable income after deductions (below 0 = unknown)
`fed_taxable_ltcg`	Preferential-rate gain inside federal taxable income (below 0 = unknown)
`has_spouse_split`	1 = the sp2_* fields carry spouse 2's shares (MFJ only)
`sp2_retirement_distributions`	Spouse 2's share of retirement_distributions
`sp2_pension_income`	Spouse 2's share of pension_income
`sp2_pension_public`	Spouse 2's share of pension_public
`sp2_roth_conversion`	Spouse 2's share of roth_conversion
`sp2_age`	Spouse's own age on a joint return (0 or less = unknown: one household age)
`wages`	Earned income (wages, net self-employment income), part of other_ordinary
`pension_military`	Military retirement pay, part of retirement_distributions and separate from pension_income
`sp2_wages`	Spouse 2's share of wages
`sp2_pension_military`	Spouse 2's share of pension_military
`pension_public_not_ss_covered`	1 = the pension_public dollars were earned without Social Security coverage (unlocks MN's and VT's non-covered pension rules, and since engine 1.4.0 OK's CSRS exclusion and ID's civil-service deduction; 0 = unknown or covered)
`blind`	1 = the filer is blind (engine 1.5.0; each state's blind amount applies)
`sp2_blind`	1 = the spouse is blind (MFJ only)
`disabled`	1 = the filer is totally and permanently disabled (engine 1.5.0; read only by the disability rules each state page lists)
`sp2_disabled`	1 = the spouse is totally and permanently disabled (MFJ only)
`dependents_given`	1 = the caller gave the dependents list (engine 1.7.0; 0 = not said: none)
`num_dependents`	Number of dependents in the list (0-20)
`dependents`	Each dependent: age at the end of the year, student, disabled
`pension_federal_civil_service`	Federal civil service annuity (CSRS / FERS), part of pension_public
`sp2_pension_federal_civil_service`	Spouse 2's share of the civil service annuity
`mfs_spouse_age`	Married filing separately: the other spouse's age (0 = not said)
`mfs_spouse_blind`	Married filing separately: 1 = the other spouse is blind
`disability_income`	Disability pay of a person retired on disability, part of pension_income
`sp2_disability_income`	Spouse 2's share of disability_income
`early_distributions_given`	1 = the filer's early IRA amount was said (0 = every IRA dollar of a person under 59)
`early_distributions`	IRA dollars taken before 59½ (household total)
`sp2_early_distributions_given`	1 = the spouse's early IRA amount was said
`sp2_early_distributions`	Spouse 2's early IRA dollars
`early_exception`	The filer's §72(t) exception: 1 none, 2 series, 3 death, 4 disability, 5 other (0 = not said)
`sp2_early_exception`	The spouse's §72(t) exception
`ira_basis`	Unrecovered after-tax IRA contributions (household total)
`sp2_ira_basis`	Spouse 2's IRA basis
`survivor_benefits`	1 = the filer's pension and IRA income is received as a beneficiary
`sp2_survivor_benefits`	1 = the spouse's is
`ss_disability`	The filer's Social Security is disability benefits: 1 yes, -1 no, 0 not said
`sp2_ss_disability`	The spouse's: 1 yes, -1 no, 0 not said
`sp2_ss_gross_given`	1 = the spouse's own gross Social Security was said (else half)
`sp2_ss_gross`	The spouse's own gross Social Security, part of ss_gross
`sp2_ss_share_year_given`	1 = a part-year period's benefits take the year's spouse share (RI, r5)
`sp2_ss_share_year`	The spouse's share of the year's gross Social Security (RI part-year Column B, r5)
`prior_hoh_qualifying_person_died`	1 = a head-of-household qualifying person of the two previous years died in those years
`ordinary_is_investment`	1 = the other ordinary income beyond wages and short-term gains is interest, dividends and other investment income (engine 1.8.0; set for the API's ordinaryIncome; 0 = untyped)
`qualifying_surviving_spouse`	1 = the return is a qualifying surviving spouse's (status single; the state's qss_rules apply)
`rr_tier2`	Railroad Retirement Tier 2 (and supplemental annuity), household total — never taxed by a state
`sp2_rr_tier2`	Spouse 2's share of rr_tier2
`rr_tier1_gross`	Railroad Retirement Tier 1 received, a part of ss_gross
`sp2_rr_tier1_gross`	Spouse 2's share of rr_tier1_gross
`qualified_dividends`	Qualified dividends, part of other_ordinary
`employer_plan`	401(k)/403(b)/457(b) distributions, part of retirement_distributions
`sp2_employer_plan`	Spouse 2's share of employer_plan
`dis_plan_min_age`	The minimum retirement age of the plan paying the filer's disability pay (0 = not said)
`sp2_dis_plan_min_age`	The same for the spouse's disability pay
`survivor_decedent_age`	The age the filer's deceased spouse would have reached by the end of the year (0 = not said)
`sp2_survivor_decedent_age`	The same for the spouse's deceased spouse
`ss_survivor`	1 = the filer's Social Security is survivor benefits
`sp2_ss_survivor`	1 = the spouse's Social Security is survivor benefits
`federal_tax_before_credits_given`	1 = federal_tax_before_credits was said
`federal_tax_before_credits`	The federal tax before credits (Form 1040 line 16 + Schedule 2 lines 2 and 8)
`federal_tax_after_credits`	1 = federal_tax is the tax after the nonrefundable credits (Form 1040 line 22); 0 = the planner's own figure, no credits taken
`federal_refundable_credits`	The federal refundable credits (Form 1040 lines 27a-30, Schedule 3 line 13a)
`capital_loss`	The year's net capital loss, positive (federal Schedule D line 16, a carryover brought in included; engine 1.9.0)
`capital_loss_carryover`	The part of capital_loss carried in from earlier years (only AL reads it)
`rental_net`	Rental real estate, signed: the federal Schedule E line 26 amount after the passive-activity limit (a profit is other ordinary income; engine 1.13.1)
`se_net_profit`	Net profit from self-employment before half the self-employment tax (API selfEmploymentIncome; read by a state business income rule, OH; library audit 2026-10-12)
`muni_interest_in_state`	Federally tax-exempt interest on the return's own state's obligations (API inStateMunicipalInterest; state engine 1.16)
`muni_interest_out_of_state`	Federally tax-exempt interest on other states' obligations (API outOfStateMunicipalInterest; state engine 1.16)
`mil_service_years`	Years of service in the uniformed services (API militaryServiceYears; 0 = not said; state engine 1.16)
`mil_medical`	Medically retired from the uniformed services (API militaryMedicalRetirement)
`veteran`	Honorably discharged veteran: 1 yes, -1 no, 0 not said (API veteran)
`ret_before_59half`	Retirement income received before 59 1/2 in the year the person reaches it (API retirementIncomeBefore59Half)
`sp2_mil_service_years`	The spouse's militaryServiceYears
`sp2_mil_medical`	The spouse's militaryMedicalRetirement
`sp2_veteran`	The spouse's veteran fact
`sp2_ret_before_59half`	The spouse's retirementIncomeBefore59Half
`federal_earned_income_credits`	Form 1040 lines 27a and 29 (API federalEarnedIncomeCredits)
`us_obligation_interest`	Interest on U.S. obligations, a part of the non-wage other ordinary income (API usObligationInterest; state engine 1.16)
`qualified_tips`	Qualified tips received as an employee (IRC 224(c)), part of the wages: [0] the filer, [1] the spouse on a joint return (API qualifiedTips; st116)
`qualified_overtime`	Qualified overtime compensation, the premium above the regular rate (IRC 225(c)), part of the wages, per person (API qualifiedOvertime)
`car_loan_interest`	Qualified passenger vehicle loan interest paid (IRC 163(h)(4); API qualifiedCarLoanInterest)
`charity_cash`	Cash gifts to public charities other than a donor-advised fund (the IRC 170(p) amount; API charityCash)
`fed_bl_given`	1 = the federal return's own below-the-line amounts are given (computeFederal)
`fed_tips_deduction`	The federal Schedule 1-A tips deduction (with fed_bl_given)
`fed_overtime_deduction`	The federal Schedule 1-A overtime deduction (with fed_bl_given)
`fed_charity_deduction`	The federal 170(p) deduction (with fed_bl_given)
`domicile_years_given`	1 = the person's domicileYears was given
`domicile_years`	The person's whole years of domicile in the state at the end of the year (API domicileYears)
`se_half_tax`	The deduction for half the self-employment tax federal AGI took from that profit (API selfEmploymentIncome with computeFederal; read by PA net profits, state engine 1.16)
`sp2_se_half_tax`	Spouse 2's share of se_half_tax (golden round 11: the local net-profits taxes add each person's half back)
`sp2_se_net_profit`	Spouse 2's share of se_net_profit (golden round 11: each person's Schedule SE line 4a for an Ohio school district)
`fed_deduction_given`	1 = the federal deduction below was said (the planner and computeFederal say it)
`fed_deduction`	The federal Form 1040 line 12e as filed (the standard or itemized deduction)
`fed_itemizes`	1 = line 12e is the itemized deduction (Schedule A line 17)
`fed_standard_deduction`	The federal standard deduction the filer could have claimed (with the age and blindness amounts)
`fed_itemized_sit`	The state income tax inside Schedule A line 5e: line 5e less lines 5b, 5c and the local income tax, not below 0
`sa_given`	1 = the federal Schedule A lines below were said (a full-year resident return)
`sa_fed_agi`	Federal AGI (Form 1040 line 11)
`sa_medical`	Schedule A line 1: medical and dental expenses
`sa_medical_deducted`	Schedule A line 4: the medical expenses over 7.5% of federal AGI
`sa_salt_income`	Schedule A line 5a: state and local income taxes
`sa_salt_real_estate`	Schedule A line 5b: real estate taxes
`sa_salt_personal`	Schedule A line 5c: personal property taxes
`sa_salt_deducted`	Schedule A line 5e: the taxes under the federal cap
`sa_interest`	Schedule A line 10: home mortgage interest
`sa_charity_cash`	Schedule A line 11: gifts by cash or check
`sa_charity`	Schedule A line 14: the gifts deducted
`sa_itemized_before_68`	Schedule A line 17 before the 2026 section 68 limitation
`sa_itemized`	Schedule A line 17
`sa_payroll_tax`	MO-A Part 2 lines 2-7: the Social Security, Medicare and self-employment taxes the federal return figures
`working_mil_retiree`	1 = the person meets Montana's working military retiree eligibility for the year (API workingMilitaryRetiree; state engine 1.26)
`sp2_working_mil_retiree`	The spouse's workingMilitaryRetiree
`sa_py_factor`	A part-year / nonresident return's proration of the state itemized deduction (GA Form 500 Schedule 3 line 13; set only by the residency computation, 0 = not prorated)
`property_tax_paid`	The year's property tax on the principal residence
`rent_paid`	The year's rent for the principal residence
`rent_includes_heat`	1 = the rent includes heat or utilities
`home_value`	The home's assessed (MA) or full (NY) value; 0 = not said
`tax_exempt_interest`	Federally tax-exempt interest
`medical_expenses`	Unreimbursed medical and dental expenses (NM 65+ credit)
`income_test_agi_given`	Engine 1.12.0 (W4): 1 = the income tests read income_test_agi (a part-year / nonresident return's state-source computation)
`income_test_agi`	The whole year's federal AGI the income tests read on a part-year / nonresident return's state-source computation
`income_test_ss`	Golden round 3: the whole year's taxable Social Security an income test that leaves the benefits out takes off income_test_agi (NJ, MO, VA; read only with income_test_agi_given)
`income_test_state_agi`	Golden round 3: the whole year's state AGI from all sources a part-year return's low-income test reads (MA Schedule NTS-L-NR/PY line 8; read only with income_test_agi_given)
`income_test_wages`	Golden round 3: the whole year's wages a part-year return's earnings test reads (NJ Worksheet E line 8; read only with income_test_agi_given)
`tax_table`	1 = the bracket tax is the state's tax table row where its form makes one mandatory (the API's default for a full-year resident return without a projection); 0 = the rate schedule on the exact amount (every C caller's default: the planner, the optimizers)

Worked examples

Engine results for four fixed households, in a few states that treat them differently (all states are on their own pages):

Household	AL	GA	NY	OK	MO	CO
Single, 67: $30,000 private pension, $20,000 IRA, $10,000 interest, $24,000 Social Security ($17,000 federally taxable), $5,000 long-term gain	$1,193.75	$0	$1,833.40	$1,929.50	$1,786.46	$1,507.88
Married filing jointly, 70: $40,000 public pension, $40,000 IRA, $20,000 interest, $40,000 Social Security ($34,000 federally taxable), $10,000 long-term gain	$2,420	$0	$544.05	$2,959	$2,569.01	$2,134
Single, 60: $60,000 other ordinary income and a $50,000 Roth conversion	$5,260	$4,740.50	$4,270.65	$3,954.50	$4,232.81	$3,251.60
Married filing jointly, 66: $30,000 IRA, a $40,000 Roth conversion, $30,000 Social Security ($25,500 federally taxable)	$2,420	$0	$544.05	$1,159	$1,441.01	$0
Single, 58: $36,000 military retirement pay and $30,000 wages	$1,246.25	$798.40	$1,023.40	$804.50	$472.81	$1,315.60
Married filing jointly, ages 67 and 61: $50,000 IRA, $10,000 interest, $30,000 Social Security ($25,500 federally taxable), each spouse's age given	$2,220	$249.50	$154.05	$709	$1,048.56	$72.60

Inputs as the engine received them are in the engine config under examples. Federal tax is not supplied, so Alabama's federal-tax deduction is not taken in these figures.