---
title: "Qualified charitable distribution (QCD) planner"
method: POST
path: "/v1/tax/qcd-plan"
tags: ["Tax"]
---

# Qualified charitable distribution (QCD) planner

`POST /v1/tax/qcd-plan`

## Request

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

For an IRA owner 70½+, a qualified charitable distribution (IRC §408(d)(8)) gives directly from the IRA to charity: it is excluded from gross income and counts toward the RMD, so it keeps the gift out of MAGI — lowering IRMAA and the §86 taxation of Social Security — and it helps even the standard-deduction retiree (for whom a charitable itemized deduction is worthless). Compares QCD vs take-the-RMD-then-donate by composing the rmd, sstax, irmaa, and tax engines, and reports each strategy's AGI / MAGI / taxable SS / income tax / IRMAA plus the net tax saving. The QCD annual limit is the IRS-indexed §408(d)(8) amount ($108,000 in 2025, $111,000 in 2026). Deterministic; not tax advice.

## Request body

- QCDPlanRequest
  - `tax_year` 2025 | 2026, required: QCD-supported years.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `age` integer, required: IRA owner's age (>= 70 for QCD eligibility, 70½).
  - `birth_year` integer: Optional; sets the SECURE 2.0 RMD beginning age (default 73).
  - `ira_balance` number, required: Prior-year-end tax-deferred balance (drives the RMD).
  - `intended_gift` number, required: Charitable gift amount; compared up to the QCD annual limit.
  - `ordinary_income` number: Pensions etc., excluding the IRA distribution.
  - `social_security_benefits` number
  - `qualified_income` number: LTCG + qualified dividends.
  - `tax_exempt_interest` number
  - `other_itemized` number: Non-charitable itemized deductions.
  - `medicare_beneficiaries` 1 | 2: Scales the per-beneficiary IRMAA surcharge.

## Response `200`

The QCD-vs-take-RMD comparison

- QCDPlanResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` QCDPlanRequest
    - `tax_year` 2025 | 2026, required: QCD-supported years.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `age` integer, required: IRA owner's age (>= 70 for QCD eligibility, 70½).
    - `birth_year` integer: Optional; sets the SECURE 2.0 RMD beginning age (default 73).
    - `ira_balance` number, required: Prior-year-end tax-deferred balance (drives the RMD).
    - `intended_gift` number, required: Charitable gift amount; compared up to the QCD annual limit.
    - `ordinary_income` number: Pensions etc., excluding the IRA distribution.
    - `social_security_benefits` number
    - `qualified_income` number: LTCG + qualified dividends.
    - `tax_exempt_interest` number
    - `other_itemized` number: Non-charitable itemized deductions.
    - `medicare_beneficiaries` 1 | 2: Scales the per-beneficiary IRMAA surcharge.
  - `result` object
    - `rmd` number: Required minimum distribution this year (0 if not yet required).
    - `rmd_required` boolean
    - `qcd_limit` number: The §408(d)(8) annual limit for the year.
    - `qcd_amount` number: The gift compared (min of intended_gift and the limit).
    - `gift_capped` boolean: True if intended_gift exceeded the QCD limit.
    - `qcd` QCDStrategy: The tax picture under one giving approach (annual dollars).
      - `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_surcharge` number: Annual Part B/D IRMAA × beneficiaries.
      - `total_cost` number: income_tax + irmaa_surcharge.
    - `take_rmd_then_donate` QCDStrategy: The tax picture under one giving approach (annual dollars).
      - `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_surcharge` number: Annual Part B/D IRMAA × beneficiaries.
      - `total_cost` number: income_tax + irmaa_surcharge.
    - `net_tax_saving` number: Take-RMD total cost minus QCD total cost (positive = QCD wins).
    - `magi_reduction` number: How much lower the QCD keeps MAGI.
    - `irmaa_reduction` number: Annual IRMAA surcharge avoided by the QCD.
    - `taxable_ss_reduction` number: Less Social Security pulled into tax.
  - `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)