---
title: "Multi-debt payoff plan (avalanche vs snowball)"
method: POST
path: "/v1/debt-payoff"
tags: ["Utilities"]
---

# Multi-debt payoff plan (avalanche vs snowball)

`POST /v1/debt-payoff`

## Request

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

Given several debts and a fixed monthly budget, simulates the avalanche (highest interest rate first) and snowball (smallest balance first) strategies month by month — paying the minimum on every debt and rolling the extra (plus freed-up minimums) into the target — and returns the payoff order, months, and total interest for each, plus how much interest and time avalanche saves. If the budget can't overcome the interest, the debt is flagged as not paid off within a 50-year horizon. Deterministic; not financial advice.

## Request body

- DebtPayoffRequest
  - `debts` object[], required
    - `label` string
    - `balance` number, required
    - `annual_rate` number, required: APR, e.g. 0.229.
    - `minimum_payment` number, required: Required monthly minimum.
  - `monthly_budget` number, required: Total available per month; must be >= the sum of minimum payments.
  - `strategy` 'avalanche' | 'snowball' | 'both'

## Response `200`

The payoff plan(s)

- DebtPayoffResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` DebtPayoffRequest
    - `debts` object[], required
      - `label` string
      - `balance` number, required
      - `annual_rate` number, required: APR, e.g. 0.229.
      - `minimum_payment` number, required: Required monthly minimum.
    - `monthly_budget` number, required: Total available per month; must be >= the sum of minimum payments.
    - `strategy` 'avalanche' | 'snowball' | 'both'
  - `result` object
    - `avalanche` DebtPayoffPlan: One strategy's outcome.
      - `strategy` 'avalanche' | 'snowball'
      - `months` integer: Months until all debts clear (600 if not).
      - `total_interest` number
      - `total_paid` number
      - `paid_off` boolean: All debts cleared within the 50-year horizon.
      - `order` object[]: Per debt, in payoff order.
        - `label` string
        - `payoff_month` integer: 0 if not paid off within the horizon.
        - `interest_paid` number
    - `snowball` DebtPayoffPlan: One strategy's outcome.
      - `strategy` 'avalanche' | 'snowball'
      - `months` integer: Months until all debts clear (600 if not).
      - `total_interest` number
      - `total_paid` number
      - `paid_off` boolean: All debts cleared within the 50-year horizon.
      - `order` object[]: Per debt, in payoff order.
        - `label` string
        - `payoff_month` integer: 0 if not paid off within the horizon.
        - `interest_paid` number
    - `interest_saved_by_avalanche` number: Present when both ran: snowball interest − avalanche interest.
    - `months_saved_by_avalanche` integer
  - `disclaimer` string

## Other responses

- `400`: Invalid request (e.g. budget below the sum of minimum payments)
- `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)