Promise-to-pay

A promise-to-pay records what a borrower committed to and then settles itself from posted payments — kept, partly kept, or broken — with nobody checking. A promise written into a note is a promise nothing can evaluate: nobody can say later whether it was kept, outreach either carries on regardless or stops for a commitment that was never met, and the borrower is chased for agreeing to something. So a promise-to-pay is a structured commitment — covered debt, amounts, dates, guardrail decision, evaluation state — measured against posted payments. Creating one moves no money.

Harbor: one call, promise or approval request

On May 1, Harbor is 22 days past due for $517.14. On the call, Maya commits to pay $260 on May 8 and $257.14 on May 22, and the agent records it before the call ends.

The route takes a numeric case ID and records an in-guardrail promise immediately. If the terms exceed configured bounds, the same call returns the exact approval request it opened instead — one submission, two possible shapes, so nothing has to decide in advance which endpoint a borrower’s terms belong to:

POST /v1/servicing/cases/1001/promises
Idempotency-Key: harbor-promise-2027-05-01-v1

{
  "loanRef": "7204",
  "planType": "INSTALLMENT",
  "installments": [
    { "amount": { "amount": 260.00, "currency": "USD" }, "dueDate": "2027-05-08" },
    { "amount": { "amount": 257.14, "currency": "USD" }, "dueDate": "2027-05-22" }
  ],
  "reason": "Customer confirmed the two-part commitment.",
  "evidenceIds": [8801]
}

The response explains each guardrail tested: maximum horizon, minimum covered percentage, installment count, first-payment timing, and any product-specific rule. It returns ACTIVE only if terms are inside policy or already approved. Naming every bound that was checked is what lets the approver see why this one needed a person, without re-deriving the policy by hand.

Money movement is separate

A promise can optionally reference future payment instructions, but it does not authorize a debit. Each later payment must have its own valid authorization and follow the payment lifecycle. This separation allows a borrower to keep a promise through the portal, ACH, card, lockbox, or another posted source.

Only posted payments count

Evaluation uses posted, value-dated payment facts from the authoritative system. Money in flight looks like money paid on every screen it appears on, and a promise marked kept on an authorization is a promise that unmarks itself a week later. The policy defines:

• which loan and transaction types count;
• whether early payments count and how they map to installments;
• grace time and the evaluation timezone;
• how reversals and returns reopen a result; and
• whether one payment can satisfy more than one promise.

For Harbor, if $260 posts effective May 8 and $257.14 posts effective May 22, the promise becomes KEPT. If the second ACH is processing on May 22, evaluation remains pending under the covering-payment policy; it does not prematurely mark kept. If that debit later returns, the prior evaluation is reversed with a linked event and follow-up work opens.

Payment events and scheduled servicing jobs drive this evaluation, so a promise’s state follows the money rather than following whoever last asked about it.

Suppression names the promise that caused it

An active promise can suppress redundant collection outreach for the covered debt and interval. Required notices, borrower-initiated responses, unrelated obligations, and legally permitted exceptions remain separately evaluated. Suppression exposes its source promise and expiry, because a worker — agent or person — that finds a channel unavailable and cannot see why will either escalate a working control or route around it.

A replacement is a new promise

Revision creates a new promise version and re-runs guardrails. The prior version becomes SUPERSEDED; payments already credited to it remain visible. Cancellation requires actor, reason, borrower request or policy basis, and effective time. A broken promise is not cancelled merely to improve performance reporting.

Both are the same implemented command, distinguished by operation:

curl -X POST "$BASE/v1/servicing/cases/1001/promises/6101/revise" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "REPLACE",
    "planType": "SINGLE",
    "promiseDate": "2027-05-15",
    "promiseAmount": { "amount": 250.00, "currency": "USD" },
    "reason": "Customer requested a one-week extension."
  }'

{
  "outcome": "COMPLETED",
  "promiseId": 6102,
  "supersedesPromiseId": 6101,
  "resourceId": 6102
}

A replacement returns a new promiseId and names what it superseded. Nothing edits promise 6101 in place, so its terms and approval history stay readable beside the commitment that replaced them. The replacement re-runs current guardrails: an extension that was in policy last week can come back as an approval request today. UPDATE_SERVICING_PROMISE authorizes both operations.

GET /v1/servicing/cases/{caseId}/promises returns the case’s promises alongside the guardrail bounds in force — maxHorizonDays, minAmountPercent, maxInstallments, and the outOfBoundsApprovalRole. Read those bounds before proposing terms to a borrower so the workspace can warn that an extension will need approval rather than discovering it at submit.

Measuring promise performance

Track created, approved, kept, partially kept, broken, cancelled, and superseded promises by terms and segment. Keep “kept at first evaluation” distinct from “later reversed after payment return”: a book measured on first evaluation flatters itself by exactly the returns it has not seen yet. Measure outreach suppressed as its own figure too, since suppression is a decision not to call somebody and not a payment received.