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

# Bill pay lifecycle

> Understand bill pay cycle statuses, state transitions, and how bills move through the payment pipeline.

This guide covers the bill pay lifecycle from a developer's perspective — the statuses a bill can occupy, valid transitions between them, and how external events (deletion, revision, charge changes) affect in-flight cycles.

## Cycle overview

Every bill that enters the bill pay pipeline gets a **cycle** — a stateful object that tracks the bill's position in the payment lifecycle. The cycle progresses through a series of statuses driven by automated evaluation, manual actions, and external signals.

## Status reference

| Status                | Category    | Description                                              | Terminal? |
| --------------------- | ----------- | -------------------------------------------------------- | --------- |
| `UNVALIDATED`         | Initial     | Bill entered the cycle, checking for data quality issues | No        |
| `VALIDATED`           | Pre-routing | Bill passed validation, awaiting review                  | No        |
| `PENDING_ROUTING`     | Pre-routing | No routing rules matched; waiting for manual assignment  | No        |
| `DELIVERED`           | Terminal    | Bill forwarded to AP team or ERP system                  | Yes       |
| `FUNDING_REQUESTED`   | In-flight   | Centralized path: waiting for customer funding           | No        |
| `FUNDING_RECEIVED`    | In-flight   | Funds received, vendor payment being initiated           | No        |
| `PAYMENT_PROCESSING`  | In-flight   | Payment in progress with provider                        | No        |
| `PAID`                | Terminal    | Vendor paid successfully                                 | Yes       |
| `PAYMENT_FAILED`      | Terminal    | Payment attempt failed                                   | Yes       |
| `CANCELLED`           | Terminal    | Cycle cancelled (bill deleted, or manual action)         | Yes       |
| `NO_PAYMENT_REQUIRED` | Terminal    | No payment needed for this bill                          | Yes       |
| `IN_EXCEPTION`        | Parked      | Issue raised; cycle pauses, resumes on resolution        | No        |
| `IN_DISPUTE`          | Parked      | Dispute opened; cycle pauses, resumes on resolution      | No        |

## State transitions

### Primary flow (delivered path)

```
UNVALIDATED → VALIDATED → [rule evaluation] → DELIVERED
```

If no rules match:

```
VALIDATED → PENDING_ROUTING → (manual assignment) → DELIVERED
```

### Primary flow (centralized path)

```
UNVALIDATED → VALIDATED → FUNDING_REQUESTED → FUNDING_RECEIVED → PAYMENT_PROCESSING → PAID
```

Payment failure:

```
PAYMENT_PROCESSING → PAYMENT_FAILED
```

### Exception and dispute parking

Any non-terminal status can transition to `IN_EXCEPTION` or `IN_DISPUTE`. When resolved, the cycle restores to its **prior status** and resumes from that point.

```
VALIDATED → IN_EXCEPTION → VALIDATED (restored)
FUNDING_REQUESTED → IN_DISPUTE → FUNDING_REQUESTED (restored)
```

### Cancellation

Most non-terminal statuses can be cancelled:

```
UNVALIDATED / VALIDATED / PENDING_ROUTING / FUNDING_REQUESTED / FUNDING_RECEIVED → CANCELLED
```

## Terminal statuses

Once a cycle reaches a terminal status, no further transitions occur:

* `PAID` — vendor paid successfully
* `DELIVERED` — bill forwarded to AP/ERP
* `CANCELLED` — cycle terminated
* `PAYMENT_FAILED` — payment attempt failed, flagged for attention
* `NO_PAYMENT_REQUIRED` — bill doesn't require payment
* `REFUNDED` — payment was refunded
* `ARCHIVED` — cycle archived administratively

## In-flight statuses (special handling)

The statuses `FUNDING_REQUESTED`, `FUNDING_RECEIVED`, and `PAYMENT_PROCESSING` represent cycles where real money movement may have begun. If a bill is deleted or revised while in one of these states, the cycle is cancelled and flagged for manual reconciliation rather than being silently terminated.

## Bill lifecycle events

### Bill deletion

| Cycle state                 | Behavior                                      |
| --------------------------- | --------------------------------------------- |
| Terminal (including `PAID`) | Event logged; no state change                 |
| In-flight                   | Cancelled + flagged for manual reconciliation |
| All other non-terminal      | Cancelled                                     |

### Bill revision

When a bill is revised (superseded by a corrected version), the old cycle is cancelled following the same rules as deletion. The new bill version creates a fresh cycle if bill pay is enabled.

### Charge amount change

| Cycle state | Behavior                                     |
| ----------- | -------------------------------------------- |
| Terminal    | No action                                    |
| In-flight   | Amount change logged + flagged for attention |
| `VALIDATED` | Cycle cancelled with reason "amount changed" |
| All other   | Amount change logged                         |

## Late-risk escalation

Bills with a due date are monitored for late-payment risk. Three escalation tiers are calculated from `dueDate - bufferDays`:

| Tier     | Trigger                      | Default timing        |
| -------- | ---------------------------- | --------------------- |
| WARNING  | `dueDate - bufferDays`       | 7 days before due     |
| URGENT   | `dueDate - (bufferDays / 2)` | \~3-4 days before due |
| CRITICAL | `dueDate - 2 days`           | 2 days before due     |

The buffer is configurable per company. Each escalation tier sends notifications to users matched by notification rules. The timer is cancelled when the cycle reaches a terminal status.

## Related pages

* [Bill Pay overview](/platform/bill-pay/overview) — end-user introduction
* [Funding overview](/platform/bill-pay/funding) — customer-facing status tracking
* [Bill pay rules API](/developer-guide/bill-pay-rules) — creating rules programmatically