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).
`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
`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)
`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

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.32	$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,568.87	$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.67	$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,440.87	$0
Single, 58: $36,000 military retirement pay and $30,000 wages	$1,246.25	$798.40	$1,023.40	$804.50	$472.67	$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.42	$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.