Tenancy Status Auto-Transition
Tenancy Status Auto-Transition
Available from v0.1.250
The platform now automatically keeps each tenancy's status field in sync with the real world. A daily background job scans every tenancy and transitions its status based on its startDate and endDate, removing the need for agents to update statuses manually.
Status Lifecycle
A tenancy moves through the following states:
upcoming → active → ended
↓
disputed
| Status | Meaning |
|---|---|
upcoming | Tenancy has been created but the start date has not yet been reached. |
active | Tenancy is currently in progress (start date has passed). |
ended | Tenancy has finished and no open deposit release exists. |
disputed | A dispute has been raised; the tenancy is held in this state until resolution. |
Auto-Transition Rules
The reconciliation job runs once per day and applies transitions in the following order:
upcoming → active
Condition: startDate <= today
When a tenancy's start date is today or in the past, it is moved to active. This ensures the tenancy appears in the dashboard work queue and is eligible for check-out reminders.
active → ended
Condition: endDate < today AND no open deposit release
When a tenancy's end date has passed, it is moved to ended — but only if there is no in-progress deposit release attached to it. This guard prevents a tenancy from being prematurely closed while a financial settlement is still being negotiated.
Notifications
Each automatic status transition triggers the appropriate notification to all relevant parties:
- Landlords and agents are notified when a tenancy becomes active or ends.
- Tenants receive a notification when their tenancy is marked as ended.
Notification content and delivery channel follow the same rules as manually triggered transitions.
Dashboard Work Queue
The dashboard work queue (src/lib/routers/dashboard.ts) queries for active tenancies ending within the next 30 days. Before this feature, tenancies that had started but were still in upcoming state were invisible to this queue. With auto-transition enabled, all tenancies are guaranteed to be in the correct state by the time agents review their queue each morning.
Implementation Detail
The auto-transition logic runs inside the existing deadline-reminders Inngest daily cron function as an additional status reconciliation step. No new infrastructure is required. The step is idempotent — running it multiple times on the same day will not produce duplicate transitions or notifications.
Edge Cases
| Scenario | Behaviour |
|---|---|
Tenancy has an open deposit release when endDate passes | Status remains active until the deposit release is resolved. |
Tenancy is in disputed state when endDate passes | No automatic transition; the dispute must be resolved first. |
startDate and endDate are the same day | Tenancy transitions upcoming → active → ended within the same daily run. |