Tax

Effective-marginal-rate map (tax topography)

Sweeps one income variable and plots the TRUE marginal rate on the next dollar across the range, surfacing the Social Security tax torpedo, IRMAA cliffs, the ACA 400%-of-FPL subsidy cliff, NIIT, and LTCG 0/15/20 stacking in one curve. A pure composite of the tax, sstax, irmaa, and healthcare engines: at each grid point it totals the annual cost (income tax + NIIT + Additional Medicare + optional IRMAA surcharge + optional ACA net premium) and forward-differences it. Each point's marginal rate is split into additive components (ordinary, ss_inclusion, ltcg, niit, irmaa_step, aca_step), and discrete cliffs (IRMAA tiers, the ACA cliff) are reported separately. Deterministic; not tax advice.

post/v1/tax/marginal-map

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/tax/marginal-map
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

tax_yearinteger required
filing_status'single' | 'mfj' | 'mfs' | 'hoh' required
ordinary_incomenumber

Base ordinary income held fixed (pensions, IRA distributions, wages, taxable interest).

social_security_benefitsnumber

Gross annual Social Security (drives the §86 torpedo).

qualified_incomenumber

LTCG + qualified dividends (also approximates net investment income for NIIT).

tax_exempt_interestnumber

Muni interest; added back into §86 provisional income and into MAGI.

sweep_variable'ordinary' | 'ltcg'

Which income component the swept dollars add to.

sweep_startnumber required
sweep_stopnumber required

Must exceed sweep_start.

sweep_stepnumber required
  1. The grid is (stop−start)/step + 1 points (max 1000).
include_irmaaboolean

Add the Medicare Part B/D IRMAA surcharge. IRMAA is assessed on a 2-year MAGI lookback; the map shows the surcharge this MAGI triggers under the tax_year schedule.

medicare_beneficiaries1 | 2

Scales the per-beneficiary IRMAA surcharge (2 = a couple both enrolled).

include_acaboolean

Add the ACA premium-tax-credit net premium (pre-65 context).

household_sizeinteger

Required when include_aca.

benchmark_annual_premiumnumber

Second-lowest-cost Silver plan, annual; required when include_aca.

statestring

FPL region for ACA: "AK" / "HI", or empty for the 48 contiguous states + DC.

Example request

{
  "tax_year": 2025
}

Response

The marginal-rate curve + cliff locations

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "marginalmap_1a2b3c4d5e6f7a8b",
  "engine_version": "marginal-map-1.0.0",
  "inputs": {
    "tax_year": 2025
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.