---
title: "Tax-loss-harvesting benefit (offset + deferral)"
method: POST
path: "/v1/tax/tlh-benefit"
tags: ["Tax"]
---

# Tax-loss-harvesting benefit (offset + deferral)

`POST /v1/tax/tlh-benefit`

## Request

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

The benefit of harvesting a capital loss. The loss offsets capital gains first (at the LTCG rate), then up to $3,000 of ordinary income (at the marginal rate, §1211(b)); the rest carries forward. Because harvesting lowers the replacement's basis, the offset is recaptured as a future long-term gain — so the result nets the immediate saving against the present value of that recapture over the reinvestment horizon. Rates are derived from taxable income. Stateless (the caller supplies the loss); a wash-sale caveat is returned. Not tax advice.

## Request body

- TLHBenefitRequest
  - `tax_year` integer, required: Supported tax year (2025 or 2026).
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `taxable_income` number, required: Sets the marginal ordinary and LTCG rates.
  - `harvestable_loss` number, required
  - `offsettable_gains` number: Capital gains the loss can offset this year (default 0).
  - `reinvestment_years` number, required: Horizon over which the deferral is valued.
  - `growth_rate` number: Discount/return rate for the deferral PV (default 0.07).

## Response `200`

TLH benefit

- TLHBenefitResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` TLHBenefitRequest
    - `tax_year` integer, required: Supported tax year (2025 or 2026).
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `taxable_income` number, required: Sets the marginal ordinary and LTCG rates.
    - `harvestable_loss` number, required
    - `offsettable_gains` number: Capital gains the loss can offset this year (default 0).
    - `reinvestment_years` number, required: Horizon over which the deferral is valued.
    - `growth_rate` number: Discount/return rate for the deferral PV (default 0.07).
  - `result` object
    - `marginal_rate` number
    - `ltcg_rate` number
    - `gains_offset` number: Loss applied against capital gains.
    - `ordinary_offset` number: Loss applied against ordinary income (≤ $3,000).
    - `carryforward` number
    - `immediate_tax_saving` number
    - `future_tax_recapture` number: Tax owed later on the lowered basis.
    - `net_present_value` number: Immediate saving − PV(recapture).
    - `wash_sale_caveat` string
  - `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)