HomeGuidesAPI Reference
Guides

Paydown Schedules and Comparisons

Paydown schedules can be generated from a subset of Debts on a Consumer using various payoff strategies. When generating multiple strategies, you can compare them to each other to better understand the outcomes.

Get a Paydown Schedule for a subset of a consumer's debts

Here's an example of how to create a paydown schedule for a consumer.

query($consumerId: UUID4!, $debtIds: [UUID4]!) {
  consumer(uuid: $consumerId) {
    paydownSchedule(
      debtIds: $debtIds,
      algorithm: AVALANCHE,
      overpaymentLimit: 15,
      goal: 60
    ) {
      schedule {
        debtId
        date
        minimum
        payment
      }
      summary {
        result
        initialPayment
        interest
        months
        name
        overpayment
      }
    }
  }
}

Example variables should include the UUID of the consumer and UUIDs of some of their debts:

{
  "consumerId": "df8f7e1b-62f0-4297-a6bc-042ac371ad72",
  "debtIds": [
    "7d825cd1-42da-46cc-bcb3-db212583fcc2",
    "719802a7-95f8-4e77-a4b2-a319f4b1f28f",
    "dc686bf6-f188-4a40-bb5f-644d168f8274"
  ]
}

The debtIds variable lets you specify which debts to include in the calculations. For best results, the debts should consist of credit cards and personal loans. Student loan repayment plan choices are not yet available in this endpoint.

Supported values for algorithm are AVALANCHE, SNOWBALL and MINIMUMS. Both Avalanche and Snowball focus on paying off individual debts sequentially to accelerate the payoff of the entire debt portfolio. Avalanche begins by focusing on the highest APR debt while Snowball begins with the lowest balance. Each of these provide similarly beneficial outcomes for the consumer. The Minimums algorithm simply projects the schedule and cost when only the minimum payments are made.

By default, the system will try to find the lowest overpayment that would clear the provided debts in 60 months (5 years). You can adjust this timeline by setting the goal to the desired number of months.

An overpaymentLimit can optionally be set to avoid recommending payments above what the consumer is able to afford. This is the amount paid in addition to the sum of the minimum payments on all of the debts.

PaydownSchedule response

The schedule output will contain a list of all payments made to meet the goal or the best payments that can be made within the overpayment limit.

The summary details the results at a high level including information such as total interest paid, how many months it took to pay off all the debts, and the amount of overpayment beyond the minimums.

Compare Summaries

Summaries (of the SummaryInput type) are returned by several other endpoints—e.g. Get Paydown Schedule for summarizing the outcome of various payoff strategies, or List Consolidation Offers for summarizing the financial outcome of alternative consolidation loans—and can be provided as-is to this endpoint to compare each summary to all the others for the purpose of finding the most benefit along various axes.

query($summaries: [SummaryInput]!) {
  compare(summaries: $summaries) {
    result
    initialPayment
    interest
    months
    name
    overpayment
    from
    interestDiff
    interestDescription
    paymentsDiff
    paymentsDescription
    monthlyPaymentDiff
    monthlyPaymentDescription
    bestFor {
      maximizeSavings
      higherEngagement
      netNewAccounts
      increasedUtilization
      newLoanDisbursement
      fastestPayoff
      primacy
      increasedAum
      lowestMonthlyPayment
      increasedDirectRevenue
    }
  }
}

Variables:

{
  "summaries": [
    {
      "initialPayment": "36.96",
      "interest": "5593.04",
      "months": 263,
      "name": "paying minimums",
      "overpayment": 0,
      "result": "paid_off"
    },
    {
      "initialPayment": "36.96",
      "interest": "1147.94",
      "months": 60,
      "name": "an accelerated paydown (snowball) plus $13",
      "overpayment": 13,
      "result": "paid_off"
    },
    {
      "initialPayment": "36.96",
      "interest": "1147.94",
      "months": 60,
      "name": "an accelerated paydown (avalanche) plus $13",
      "overpayment": 13,
      "result": "paid_off"
    }
  ]
}

Compare Response

The Compare endpoint returns one listing for each pair of summaries that was provided, in order to be able to accurately compare any strategies to each other.

Several of the fields returned in a comparison are the same fields you provided in the summary: initialPayment, interest, months, name, overpayment, and result. You can think of a comparison as a summary with additional information included.

The added information centers around the from field which tells you the other summary that this one is being compared with. The rest of the fields relate to this comparison. The *Diff fields provide numerical differences between the two options, while the *Description fields explain the same results in text suitable for showing to a user. Finally, the bestFor identifiers highlight the best outcomes for choosing this option over the from option.