---
title: "Survivor / widow(er)'s-penalty tax transition projection"
method: POST
path: "/v1/tax/survivor-transition"
tags: ["Tax"]
---

# Survivor / widow(er)'s-penalty tax transition projection

`POST /v1/tax/survivor-transition`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/survivor-transition`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Projects the "widow's penalty": when the first spouse dies, the survivor files single instead of jointly — brackets compress, the §86 Social Security and IRMAA thresholds roughly halve, and one Social Security benefit stops. Prices the household both ways (MFJ while both alive vs the survivor filing single) by composing the tax, sstax, and irmaa engines, and reports each scenario's AGI / MAGI / taxable SS / income tax / IRMAA, the annual widow's penalty, the income lost, and the marginal-rate jump. With conversion_amount, it also values accelerating a Roth conversion into the cheaper still-MFJ years. Deterministic; not tax advice.

## Request body

- SurvivorTransitionRequest
  - `tax_year` 2025 | 2026, required: Tables used for both scenarios.
  - `ordinary_income` number, required: Pensions, IRA/RMD withdrawals, interest — while both alive, excluding SS.
  - `qualified_income` number: LTCG + qualified dividends (portfolio rolls to the survivor).
  - `tax_exempt_interest` number: Muni interest (added back for §86 + IRMAA MAGI).
  - `social_security_higher` number, required: The larger annual benefit — the survivor keeps this.
  - `social_security_lower` number, required: The smaller — stops at the first death. Must not exceed social_security_higher.
  - `survivor_ordinary_income` number: Ordinary income continuing to the survivor. Omit to default to ordinary_income (accounts roll over, RMDs continue).
  - `conversion_amount` number: Optional Roth conversion valued now (MFJ) vs as the survivor.

## Response `200`

The MFJ-vs-survivor comparison and conversion arbitrage

- SurvivorTransitionResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SurvivorTransitionRequest
    - `tax_year` 2025 | 2026, required: Tables used for both scenarios.
    - `ordinary_income` number, required: Pensions, IRA/RMD withdrawals, interest — while both alive, excluding SS.
    - `qualified_income` number: LTCG + qualified dividends (portfolio rolls to the survivor).
    - `tax_exempt_interest` number: Muni interest (added back for §86 + IRMAA MAGI).
    - `social_security_higher` number, required: The larger annual benefit — the survivor keeps this.
    - `social_security_lower` number, required: The smaller — stops at the first death. Must not exceed social_security_higher.
    - `survivor_ordinary_income` number: Ordinary income continuing to the survivor. Omit to default to ordinary_income (accounts roll over, RMDs continue).
    - `conversion_amount` number: Optional Roth conversion valued now (MFJ) vs as the survivor.
  - `result` object
    - `joint` SurvivorScenario: The tax picture under one filing status (annual dollars).
      - `filing_status` 'mfj' | 'single'
      - `agi` number
      - `magi` number: AGI + tax-exempt interest (IRMAA basis).
      - `taxable_ss` number: §86 taxable Social Security.
      - `income_tax` number: Federal income tax + NIIT + Additional Medicare.
      - `irmaa` number: Annual Part B/D surcharge × beneficiaries.
      - `total_cost` number: income_tax + irmaa.
      - `marginal_rate` number: Federal marginal rate on the next ordinary dollar.
      - `beneficiaries` integer: Medicare beneficiaries priced for IRMAA (2 joint, 1 survivor).
    - `survivor` SurvivorScenario: The tax picture under one filing status (annual dollars).
      - `filing_status` 'mfj' | 'single'
      - `agi` number
      - `magi` number: AGI + tax-exempt interest (IRMAA basis).
      - `taxable_ss` number: §86 taxable Social Security.
      - `income_tax` number: Federal income tax + NIIT + Additional Medicare.
      - `irmaa` number: Annual Part B/D surcharge × beneficiaries.
      - `total_cost` number: income_tax + irmaa.
      - `marginal_rate` number: Federal marginal rate on the next ordinary dollar.
      - `beneficiaries` integer: Medicare beneficiaries priced for IRMAA (2 joint, 1 survivor).
    - `annual_widow_penalty` number: Survivor total cost − joint total cost.
    - `income_lost` number: Dropped SS benefit + lost ordinary income.
    - `marginal_rate_jump` number: Survivor marginal rate − joint marginal rate.
    - `conversion` object: Present only when conversion_amount > 0.
      - `amount` number
      - `cost_now_mfj` number: Extra tax + IRMAA to convert while both alive.
      - `cost_as_survivor` number: Extra tax + IRMAA to convert as the single survivor.
      - `saving` number: cost_as_survivor − cost_now_mfj (positive = convert now).
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)