Fixed-Term Tenancy Renewal Wizard

The renewal wizard provides a guided, 3-stage workflow for renewing a fixed-term tenancy. It is available on any active or expiring tenancy and handles creating the new term, closing the old one, and updating all related records in a single operation.

Accessing the Wizard

The wizard can be opened from three places on the tenancy detail page:

Entry point	Where to find it
Action Renewal button	Tenancy overview header (active/expiring tenancies)
Action Renewal banner	Legacy expiring tenancy notice bar
Start New Renewal button	Renewals tab

All three entry points open the same wizard modal, pre-populated with data from the current term.

Wizard Flow

[Action Renewal button]
        │
        ▼
  ┌─────────────┐      Skip & Create Term
  │   Stage 1   │ ──────────────────────────────► [12-month renewal created]
  │  Length &   │
  │   Service   │
  └──────┬──────┘
         ▼
  ┌─────────────┐
  │   Stage 2   │
  │    Rent     │
  └──────┬──────┘
         ▼
  ┌─────────────┐
  │   Stage 3   │
  │   People    │
  └──────┬──────┘
         ▼
  ┌─────────────┐
  │   Review    │
  │   Screen    │
  └──────┬──────┘
         ▼
   [Submit → new term created]

A step indicator in the modal header shows progress through the three stages.

Stage Details

Stage 1 — Tenancy Length & Service

Contract length: Quick-select buttons for 6, 12, 18, 24, and 36 months. A custom number input accepts any value between 1 and 120 months.
Date preview: Computed new start date (= current term end date) and new end date are shown live as the length is adjusted.
Service type (optional): Toggle one of: Fully Managed, Let Only, Rent Collection, Tenant Find.

Stage 2 — Rent

Monthly rent (£): Accepts a decimal value. If the value differs from the current term rent, both the current and new amounts are displayed side by side.
Advance rent balance (weeks, optional): Integer 0–52. Indicates how many weeks of rent are held in advance.

Stage 3 — People

Tenant name and email: Pre-filled from the current term.
Landlord name and email: Pre-filled from the current term.
Notes (optional): Free-text field for any additional information.

Review Screen

Displays a summary of all entered values before final submission. The user can go back to any previous stage to make changes.

Skip & Create Term

When all details on the current term are unchanged, the Skip & Create Term shortcut is available from Stage 1. Clicking it immediately creates a new 12-month term without stepping through the remaining stages.

The shortcut is shown only when the unchanged-detection check passes (tenant name, landlord name, rent, and service type all match the current term).

What Happens on Submit

The createRenewalTerm mutation performs the following in a single operation:

Marks the current tenancy_term record status as ended.
Creates a new tenancy_term record with:
- Start date = current term end date
- End date = start date + selected number of months
- Rent, advance rent weeks, service type, and party details from the wizard
Updates the parent tenancies record with the new dates, rent, and tenant name.
If a linked renewal record exists, transitions it to renewed status and stores the newTermId.
Writes a full audit log entry for the term creation.

After a successful submission the user is redirected back to the tenancy overview, which displays the new term.

API Reference

`renewals.getTermForRenewal`

Type: Query

Loads the current term data for a given tenancy to pre-populate the wizard form.

Field	Type	Description
`id`	`string`	Term record ID
`propertyId`	`string`	Associated property ID
`propertyAddress`	`string \| null`	Display address
`tenantName`	`string \| null`	Current tenant name
`tenantEmail`	`string \| null`	Current tenant email
`landlordName`	`string \| null`	Current landlord name
`landlordEmail`	`string \| null`	Current landlord email
`termStartDate`	`Date`	Current term start
`termEndDate`	`Date`	Current term end (= new term start)
`monthlyRent`	`string \| null`	Current monthly rent

`renewals.createRenewalTerm`

Type: Mutation

Creates a new term from the wizard form data and closes the current term.

Input fields:

Field	Type	Required	Description
`currentTermId`	`string`	✅	ID of the term being renewed
`tenancyId`	`string`	✅	Parent tenancy ID
`renewalId`	`string \| null`	—	Linked renewal record to transition
`contractMonths`	`number`	✅	New term length in months
`serviceType`	`string`	—	Management service type
`monthlyRent`	`string`	✅	New monthly rent
`advanceRentWeeks`	`number`	—	Weeks of advance rent held
`tenantName`	`string`	✅	Tenant full name
`tenantEmail`	`string`	—	Tenant email address
`landlordName`	`string`	✅	Landlord full name
`landlordEmail`	`string`	—	Landlord email address
`notes`	`string`	—	Optional free-text notes

Returns: The newly created tenancy_term record ID.