> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Promise to Pay

> Record, track and evaluate resident commitments to pay — including instalment arrangements and renegotiations.

**Finance → Collections → Promise to Pay → `/payment-promises`** <sup>Beta</sup>

A **Promise to Pay** is a recorded commitment from a resident: an amount, by a date, optionally
split into instalments. Recording it is what turns "he said he'd pay on Friday" from a note in
somebody's head into something the system tracks, evaluates and reports on.

<Note>
  This surface was previously labelled *Payment Promises*. It is the same module — the name changed
  to match how officers talk about it.
</Note>

## Why it matters

A recorded promise does three things a note cannot:

1. **Pauses the dunning ladder** on steps configured to pause on an active promise, so a tenant who
   is cooperating does not get a demand letter three days later.
2. **Is evaluated automatically** against actual payments — kept, partially kept, or missed — with
   no manual reconciliation.
3. **Feeds the collectability score.** Promise-kept ratio and how recently a promise was broken are
   both scoring features, so a tenant's track record follows them.

## Recording a promise

<Steps>
  <Step title="Start from the case or the module">
    From a [collection case](/guides/collections/worklist-and-cases), logging an interaction with
    the outcome **promises** deep-links straight into creating one. You can also go to
    **Promise to Pay → Create**.
  </Step>

  <Step title="Set the amount and date">
    The total the resident has committed to, and when.
  </Step>

  <Step title="Add instalments if it is an arrangement">
    Split the total across dated instalments. Each instalment is evaluated on its own, so a tenant
    paying two of three is *partially fulfilled*, not simply "missed".
  </Step>

  <Step title="Link it to the debt">
    The promise is linked to the lease and, where relevant, to the invoices it is meant to settle.
  </Step>

  <Step title="Save">
    The promise becomes active, the ladder pauses where configured, and reminders are scheduled.
  </Step>
</Steps>

## Statuses

| Status                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| **Pending**             | Made, not yet due.                              |
| **Reminded**            | A reminder has been sent ahead of the due date. |
| **Fulfilled**           | Paid in full, on or before the date.            |
| **Partially fulfilled** | Some of the committed amount was received.      |
| **Missed**              | The date passed without sufficient payment.     |
| **Cancelled**           | Withdrawn before evaluation.                    |
| **Renegotiated**        | Superseded by a new promise.                    |

Evaluation is done against actual payments and allocations on the lease — not by anybody ticking a
box.

## Renegotiation

When a resident cannot meet a promise and agrees a new arrangement, **renegotiate** rather than
edit. Renegotiation:

* marks the old promise terminal and links the new one to it, preserving the chain;
* cancels only the **pending** instalments of the old schedule;
* never overwrites history — you can always see how many times an arrangement has been reset.

<Warning>
  Editing a promise's amount or date to "fix" it destroys the track record that scoring and reporting
  depend on. Renegotiate instead.
</Warning>

## The list

The list shows every promise with its status chips, amount, promised date, received amount, lease,
resident and linked case. Filter by status to build the two queues that matter operationally:

* **Due today** — promises falling due now, ready for a pre-emptive reminder.
* **Missed** — promises that failed, which should resume the ladder and raise case severity.

## Promise detail

The detail page shows the commitment, the instalment schedule with each instalment's own state,
the received amount to date, the linked lease and invoices, the renegotiation chain, and the
timeline of reminders sent.

## How promises interact with collections

| Event                  | Effect on the case                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| Promise created        | Treatment state moves to *promise*; ladder steps flagged to pause on promise are suspended. |
| Promise kept           | Case moves toward clearing as the balance drops; the kept ratio improves.                   |
| Promise partially kept | Ladder resumes on the shortfall; severity is not escalated as hard as a full miss.          |
| Promise missed         | Ladder resumes, severity is bumped, and a follow-up task is staged.                         |
| Promise renegotiated   | The new schedule takes over; the case timeline records both.                                |

## Good practice

* Record the promise **during** the call, not after. An unrecorded promise is invisible to the
  engine, and the tenant will get the next ladder step.
* Split anything above one month's rent into instalments — a single large promise is far more
  likely to be missed outright, and a miss is harsher on the score than a partial.
* Set the promised date to a date the tenant chose. Promises with dates imposed by the officer have
  a materially worse kept rate.
* Check the **Missed** queue daily; a missed promise is the strongest single signal that a case
  needs escalation.