Retirement

Plan a year of tax-aware retirement withdrawals

Decides how much to withdraw from taxable, tax-deferred, and tax-free (Roth) accounts to net a target after-tax spending amount, accounting for the tax the withdrawals themselves generate. Supports three strategies (conventional, bracket_fill, proportional), models taxable cost basis so only the gain is taxed, and — when an age is supplied — takes the year's RMD from the tax-deferred account first. Calculation engine output, not tax advice. Deterministic.

post/v1/retirement/withdrawal-sequencing

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/retirement/withdrawal-sequencing
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

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

After-tax cash needed this year.

strategy'conventional' | 'bracket_fill' | 'proportional' required

conventional = taxable -> tax-deferred -> Roth; bracket_fill = tax-deferred up to a target bracket then Roth/taxable; proportional = pro-rata across accounts.

bracket_ceilingnumber

Target marginal ordinary rate to fill up to. Required for the bracket_fill strategy.

taxable_balancenumber
tax_deferred_balancenumber
tax_free_balancenumber
taxable_cost_basis_fractionnumber

Share of a taxable withdrawal that is return of basis (untaxed); the rest is a long-term gain.

other_ordinary_incomenumber

Other ordinary income this year (sets the tax baseline).

other_qualified_incomenumber

Other long-term gains / qualified dividends this year.

state_tax_ratenumber
ageinteger

Optional. If set, the year's RMD is taken from the tax-deferred account first.

birth_yearinteger

Optional. Sets the SECURE 2.0 RMD beginning age.

Example request

{
  "tax_year": 2025,
  "spending_need": 90000,
  "bracket_ceiling": 0.22
}

Response

Withdrawal plan

result_idstring
engine_versionstring
disclaimerstring

Example response

{
  "result_id": "wd_1a2b3c4d5e6f7a8b",
  "engine_version": "withdrawal-1.0.0",
  "inputs": {
    "tax_year": 2025,
    "spending_need": 90000,
    "bracket_ceiling": 0.22
  }
}

Changes

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