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.
| 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, 401(k), 403(b) and 457 distributions, excluding conversions | Several states exclude pensions but not IRAs, or gate IRA dollars by age. |
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 | Connecticut's 25% cap and Maine's and Maryland's pension offsets use gross benefits. |
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. 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.
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) |
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,185 | $0 | $1,833 | $1,929.50 | $1,786.32 | $1,843.60 |
| 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,245 | $0 | $544.05 | $2,959 | $2,568.87 | $2,807.20 |
| Single, 60: $60,000 other ordinary income and a $50,000 Roth conversion | $5,235 | $4,740.50 | $4,269.75 | $3,954.50 | $4,232.67 | $4,131.60 |
| Married filing jointly, 66: $30,000 IRA, a $40,000 Roth conversion, $30,000 Social Security ($25,500 federally taxable) | $2,245 | $0 | $544.05 | $1,159 | $1,440.87 | $673.20 |
| Single, 58: $36,000 military retirement pay and $30,000 wages | $1,235 | $798.40 | $1,023 | $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,045 | $249.50 | $154.05 | $709 | $1,048.42 | $409.20 |
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.