Input schema (JSON)
{
"type": "object",
"required": [
"cards"
],
"properties": {
"cards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"maxLength": 120,
"description": "Card label, e.g. 'Chase Sapphire', 120 characters or fewer. Optional; a card without a name is auto-numbered ('Card 1', 'Card 2', and so on). Echoed into per-card results and warning text. A name over the cap is replaced in error field paths by a key built from its zero-based card index, written as '#0 (name over cap)', '#1 (name over cap)' and so on."
},
"segments": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"required": [
"type",
"balance"
],
"properties": {
"type": {
"type": "string",
"description": "Segment type. REQUIRED on every segment: omitting it is rejected. Per-type field matrix. Every field below is classified for every segment type: REQUIRED (omitting it is rejected), OPTIONAL (accepted either way and read), PAIRED (read when supplied together with its partner as a usable pair: promo_expires_month and revert_apr_pct both supplied beside a supplied apr_pct, each within its value rule; a pair that is not usable is rejected when the segment carries a balance and its apr_pct is omitted, 0 or below, and otherwise is not used, with an INPUT_NOT_USED warning; omitting both, or sending both as null, is accepted), IGNORED (accepted and never read for this type, though a value can still fail the field's own range check), or REJECTED (supplying a disallowed value is an error; the field's own rule below says exactly which values are disallowed). Value rules are stated separately from applicability, because a field can be accepted on a type and still be restricted there. The validators are the authority; this matrix describes them.\n- type: REQUIRED on every type. Values: one of purchase, cash_advance, balance_transfer, promotional, installment_plan.\n- balance: REQUIRED on every type. Values: $0 to $1,000,000,000; above $50,000 returns a HIGH_CARD_BALANCE warning, not an error.\n- apr_pct: REQUIRED on purchase, cash_advance, balance_transfer, promotional; OPTIONAL on installment_plan. Values: 0 to 100 as a percentage, e.g. 24.99 not 0.2499. The REQUIRED classification above applies when balance is greater than 0; a zero-balance segment may omit it. Must be greater than 0 on cash_advance carrying a balance, unless that segment carries a usable promo pair (promo_expires_month and revert_apr_pct). Must equal 0 on installment_plan, where omitting it is the correct shape.\n- revert_apr_pct: REQUIRED on balance_transfer, promotional; PAIRED on cash_advance; IGNORED on purchase; REJECTED on installment_plan. Values: 0 to 100, and at least apr_pct. Rejected on installment_plan with FIELD_NOT_ALLOWED_HERE: an expired plan's residual keeps its existing rate.\n- promo_expires_month: REQUIRED on balance_transfer, promotional; PAIRED on cash_advance; IGNORED on purchase, installment_plan. Values: 1 to 480.\n- monthly_fee: OPTIONAL on installment_plan; REJECTED on purchase, cash_advance, balance_transfer, promotional. Values: $0 or more, and no greater than plan_payment_due, on installment_plan. On every other type a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; 0 and a negative value are accepted and dropped there.\n- plan_payment_due: REQUIRED on installment_plan; REJECTED on purchase, cash_advance, balance_transfer, promotional. Values: greater than $0, at least monthly_fee, and no more than $1,000,000,000, on installment_plan. On every other type a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; 0 and a negative value are accepted and dropped there.\n- remaining_payments: OPTIONAL on installment_plan; IGNORED on purchase, cash_advance, balance_transfer, promotional. Values: 0 or more. 0 means the stated term has ALREADY ended and is valid with any balance. From 1 up, balance must be clearable within the stated term.\n- min_payment_order: OPTIONAL on every type. Values: 1 or more; breaks a tie only between segments sharing both the same current APR and the same installment-plan status.\n- extra_payment_order: OPTIONAL on every type. Values: 0 or more; 0 means skip. Breaks a tie only between segments sharing the exact same current APR.\n- merchant_name: OPTIONAL on installment_plan; IGNORED on purchase, cash_advance, balance_transfer, promotional. Values: 120 characters or fewer.\n- monthly_spend: OPTIONAL on purchase; REJECTED on cash_advance, balance_transfer, promotional, installment_plan. Values: $0 to $50,000 per month. A negative value is rejected as NEGATIVE_BALANCE on every type, purchase included. On every type other than purchase a POSITIVE value is rejected with FIELD_NOT_ALLOWED_HERE; an explicit 0 is accepted.\n- stop_spend_month: OPTIONAL on purchase; IGNORED on cash_advance, balance_transfer, promotional, installment_plan. Values: 0 or more; range checked on every type, read only on purchase."
},
"apr_pct": {
"type": [
"number",
"null"
],
"default": null,
"description": "Annual percentage rate for this segment, 0 to 100, e.g. 24.99 not 0.2499. Required when balance is greater than 0 on purchase, cash_advance, balance_transfer and promotional. On cash_advance with a balance it must be supplied and greater than 0, unless the segment also carries a usable promo_expires_month and revert_apr_pct: then it is the promotional rate and may be 0. Must be 0 on installment_plan, which uses monthly_fee instead, so omitting it there is the correct shape."
},
"balance": {
"type": "number",
"description": "Segment balance in dollars, $0 to $1,000,000,000. REQUIRED on every segment type: an omitted balance would silently report a $0, 0-month payoff, so it is rejected instead. An explicit 0 is valid, for example a paid-off balance_transfer segment kept for schedule continuity."
},
"monthly_fee": {
"type": [
"number",
"null"
],
"default": null,
"description": "Fixed fee charged each month while an installment plan's term is active, $0 or more and no greater than plan_payment_due. Optional on installment_plan. On every other type a positive value is rejected with FIELD_NOT_ALLOWED_HERE, while 0 and a negative value are accepted and dropped."
},
"merchant_name": {
"type": [
"string",
"null"
],
"default": null,
"description": "Label for an installment plan's merchant, 120 characters or fewer. Optional on installment_plan, ignored on every other type."
},
"monthly_spend": {
"type": [
"number",
"null"
],
"default": null,
"description": "Recurring monthly purchase amount posted to this segment before interest accrues, $0 to $50,000 per month. Optional on purchase. A negative value is rejected as NEGATIVE_BALANCE on every type. On every type other than purchase a positive value is rejected with FIELD_NOT_ALLOWED_HERE, since those balances do not accept new purchases; an explicit 0 is accepted."
},
"revert_apr_pct": {
"type": [
"number",
"null"
],
"default": null,
"description": "Rate this segment reverts to once its promo expires, 0 to 100, and at least apr_pct: the post-promo APR the offer disclosed, wherever the offer or the statement prints it. Only when neither prints one for this balance, take the regular rate of this balance's category, not the promo rate. A direct-deposit or check cash advance reverts to the cash-advance APR for those advances, which can differ from the bank cash-advance APR and is not the balance-transfer APR. Required on balance_transfer and promotional. On cash_advance, supply it with promo_expires_month: alone or invalid, the pair is not used and an INPUT_NOT_USED warning says why, except at an apr_pct of 0 with a balance, where the request is rejected. Ignored on purchase. Rejected on installment_plan with FIELD_NOT_ALLOWED_HERE: an expired plan's residual keeps its existing rate rather than repricing."
},
"plan_payment_due": {
"type": [
"number",
"null"
],
"default": null,
"description": "Locked monthly payment for an installment plan, principal plus monthly_fee. Required on installment_plan, greater than $0, at least monthly_fee, and no more than $1,000,000,000. On every other type a positive value is rejected with FIELD_NOT_ALLOWED_HERE, while 0 and a negative value are accepted and dropped."
},
"stop_spend_month": {
"type": [
"integer",
"null"
],
"default": null,
"description": "Month index at which recurring spend stops, 0 or more. Read on purchase only, and range checked on every type. Omit to spend for the whole projection."
},
"min_payment_order": {
"type": [
"integer",
"null"
],
"default": null,
"description": "Minimum-payment tie-break priority, 1 or more. Optional on every type. The minimum first pays any installment_plan's locked plan_payment_due in full, then the lowest-current-APR segment; this value only breaks a tie between segments sharing both the same current APR and the same installment-plan status."
},
"remaining_payments": {
"type": [
"integer",
"null"
],
"default": null,
"description": "Payments left in an installment plan's stated term, 0 or more. Optional on installment_plan, ignored on every other type. 0 means the term has ALREADY ended and is valid with any balance, including a positive residual. From 1 up, the balance must be clearable within the stated term and must not be clearable a month early."
},
"extra_payment_order": {
"type": [
"integer",
"null"
],
"default": null,
"description": "Extra-payment tie-break priority, 0 or more, where 0 means this segment never receives extra payment. Optional on every type, and the default for installment_plan. Only breaks a tie between segments sharing the exact same current APR, since the Credit CARD Act (TILA §164(b), 15 U.S.C. §1666c(b)) / 12 CFR 1026.53(a) always pays the highest-current-APR segment first regardless of this value."
},
"promo_expires_month": {
"type": [
"integer",
"null"
],
"default": null,
"description": "Last month charged at apr_pct, 1 to 480; revert_apr_pct applies from the next month. Month 1 is the first statement cycle after the statement the balance comes from. From a statement, count the closing dates after it, up to and including the last one on or before the promo end date; a cycle the end date splits counts at revert_apr_pct. If no closing date qualifies, the promo ends inside month 1: enter the post-promo rate as both apr_pct and revert_apr_pct, with promo_expires_month 1. Required on balance_transfer and promotional. On cash_advance, supply it with revert_apr_pct, under the rule stated on revert_apr_pct. Ignored on purchase and installment_plan."
}
}
},
"description": "Per-segment breakdown of this card's balances. Optional; when it carries at least one segment it SUPERSEDES purchase_balance and cash_advance_balance, and a POSITIVE value in either of those is rejected. An empty segments[] is treated as absent, so purchase_balance is then required. At most 100 segments across the whole request. Per card, per type: 1 purchase, 1 cash_advance, 5 balance_transfer, 1 promotional, 10 installment_plan. Each item carries its own type, balance, rate and payment priority; see the type field on the item for the per-type field matrix."
},
"annual_fee": {
"type": [
"number",
"null"
],
"description": "Annual fee in dollars, $0 to $1,000,000,000. Optional; defaults to 0. Charged at month 1 and every twelfth month after, while the card carries a balance."
},
"monthly_spend": {
"type": [
"number",
"null"
],
"description": "Recurring monthly purchase amount charged to this card's purchase balance before interest accrues, $0 to $50,000 per month. Optional; defaults to 0. Use the segment-level monthly_spend instead when supplying segments[]."
},
"minimum_payment": {
"type": [
"number",
"null"
],
"description": "Minimum payment in dollars, $0 to $1,000,000,000 (optional, omit or set 0 to auto-calculate). Where it binds, the card is locked at max(minimum_payment, that card's issuer minimum computed at month 1), and that locked amount is paid every month. On calculate_cc_payoff it binds ONLY when fixed_payments = true; on the DEFAULT path (fixed_payments = false) it is NOT used, because the plan recomputes each card's issuer minimum from its current balance every month, and the response discloses that as MINIMUM_PAYMENT_NOT_BINDING. On compare_payoff_strategies there is no fixed_payments parameter and supplying one is rejected: the avalanche and snowball arms ALWAYS run locked, so the value DOES bind and moves both arms, while the minimum-payments-only baseline always recomputes and ignores it, disclosed as MINIMUM_PAYMENT_NOT_BINDING_IN_BASELINE."
},
"purchase_apr_pct": {
"type": [
"number",
"null"
],
"maximum": 100,
"minimum": 0,
"description": "Purchase APR as a percentage, 0 to 100, e.g. 24.99 not 0.2499. Required when purchase_balance is greater than 0: an omitted APR would silently compute $0 interest."
},
"purchase_balance": {
"type": [
"number",
"null"
],
"description": "Purchase balance in dollars, $0 to $1,000,000,000. Required unless segments[] carries at least one segment: an omitted purchase_balance would silently report a $0, 0-month payoff. Supplying a POSITIVE value alongside a non-empty segments[] is rejected, since the two would be competing sources for the same balance. An explicit 0 is accepted."
},
"stop_spend_month": {
"type": [
"integer",
"null"
],
"description": "Month index at which this card's recurring spend stops, 0 or more. Optional; omit to spend for the whole projection."
},
"plan_fees_monthly": {
"type": [
"number",
"null"
],
"description": "Recurring monthly card fee in dollars, $0 to $1,000,000,000, e.g. a pay-over-time plan fee. Optional; defaults to 0. Charged every month while the card carries a balance."
},
"cash_advance_apr_pct": {
"type": [
"number",
"null"
],
"description": "Cash advance APR as a percentage, greater than 0 and up to 100. Required when cash_advance_balance is greater than 0. These flat fields have no promo input, so 0 is rejected: nothing would say when a 0% rate ends. For a promotional cash advance, such as a 0% direct-deposit or check offer, use segments[] with a cash_advance segment carrying promo_expires_month and revert_apr_pct."
},
"cash_advance_balance": {
"type": [
"number",
"null"
],
"description": "Cash advance balance in dollars, $0 to $1,000,000,000. Optional; defaults to 0 when omitted. A POSITIVE value alongside a non-empty segments[] is rejected, the same way purchase_balance is. An explicit 0 is accepted."
}
}
},
"maxItems": 20,
"description": "Credit cards to pay off, 1 to 20. Required: omitting the field answers contract_error MISSING_REQUIRED_FIELD, while an explicit JSON null answers parse_error (\"cards is required and must be an array.\"); the two are not the same rejection. Every card may carry segments[]. Max 100 segments total across all cards in the request. Per-card, per-type caps: 1 purchase, 1 cash_advance, 5 balance_transfer, 1 promotional, 10 installment_plan."
},
"output": {
"enum": [
"summary",
"inline",
null
],
"type": [
"string",
"null"
],
"description": "Valid values: 'summary' (default), 'inline'. summary returns a compact response with a data_preview block; inline returns the full payload."
},
"strategy": {
"enum": [
"avalanche",
"snowball",
null
],
"type": [
"string",
"null"
],
"default": null,
"description": "Payoff order: 'avalanche' pays the highest APR first, 'snowball' the smallest balance first. Optional; defaults to 'avalanche' when omitted. Matched case-insensitively, and the response echoes the canonical lowercase form actually simulated."
},
"windfalls": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"properties": {
"label": {
"type": [
"string",
"null"
],
"maxLength": 120,
"description": "Optional label for this windfall, e.g. 'Tax refund' or 'Year-end bonus'. Max 120 characters."
},
"month": {
"type": [
"integer",
"null"
],
"description": "Month index the windfall is applied, 0 or more. 0 means applied before month 1's interest; N >= 1 applies at the end of calendar month N. Required per entry."
},
"amount": {
"type": [
"number",
"null"
],
"description": "Dollar amount of the windfall, greater than 0. Required per entry."
}
}
},
"default": null,
"maxItems": 12,
"description": "One-time principal payments, at most 12, e.g. a tax refund or a year-end bonus. Optional; a JSON null is treated as omitted. When non-empty the response gains baseline, with_windfalls, months_saved_vs_baseline, interest_saved_vs_baseline, windfalls_applied[] and windfalls_unused[]; an empty array returns the same shape as omitting it."
},
"chart_title": {
"type": [
"string",
"null"
],
"default": null,
"maxLength": 120,
"description": "Override for the chart title. Optional; must not contain an em dash or en dash. Max 120 characters."
},
"per_segment": {
"type": [
"boolean",
"null"
],
"default": null,
"description": "Whether each schedule row carries its per-segment breakdown. Optional; defaults to true when omitted."
},
"full_schedule": {
"type": [
"boolean",
"null"
],
"default": null,
"description": "Whether to return the full per-card month-by-month schedule. Optional; defaults to false when omitted. The per-card monthly_schedule is capped at 1000 rows total across cards and months, so later months are omitted on a long multi-card payoff; the portfolio-level monthly_totals series is always complete and is the one to read for the whole timeline."
},
"apply_rate_cap": {
"type": [
"boolean",
"null"
],
"default": null,
"description": "Whether to cap each card's APR at the regulatory ceiling before simulating. Optional; defaults to false when omitted."
},
"fixed_payments": {
"type": [
"boolean",
"null"
],
"default": null,
"description": "Whether to hold each card's payment constant for the whole payoff. Optional; defaults to false when omitted. When true, each card's payment is locked at max(cards[].minimum_payment, that card's issuer minimum computed at month 1), and the total monthly budget (those locked amounts plus extra_monthly_payment) is held constant for the whole payoff, so once a card is paid off its freed-up payment rolls forward onto the remaining cards. This is the ONLY mode in which cards[].minimum_payment affects calculate_cc_payoff's result; compare_payoff_strategies has no fixed_payments parameter and binds minimum_payment on both of its strategy arms regardless."
},
"extra_monthly_payment": {
"type": [
"number",
"null"
],
"default": null,
"description": "Extra monthly payment in dollars, $0 to $1,000,000,000, applied on top of the required minimums. Optional; defaults to 0 when omitted."
},
"include_card_timeline": {
"type": [
"boolean",
"null"
],
"default": null,
"description": "Whether to add the card_timeline block, a per-card view of when each card clears. Optional; defaults to false when omitted."
}
}
}