Skip to main content
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

​
State transitions

​
Primary flow (delivered path)

If no rules match:

​
Primary flow (centralized path)

Payment failure:

​
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.

​
Cancellation

Most non-terminal statuses can be 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

​
Bill revision

When usage on a bill is linked as a revision (superseded by a corrected bill), the old cycle is cancelled following the same rules as deletion. The revising bill creates a fresh cycle if bill pay is enabled. Linking is per usage row; the first incoming revision link on a bill triggers cycle cancellation for that bill’s pay cycle.

​
Charge amount change

​
Late-risk escalation

Bills with a due date are monitored for late-payment risk. Three escalation tiers are calculated from dueDate - bufferDays: 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.