Tenants

First-time workspace setup

Open Tenants as setup step 15 after Bookings (step 14) and Listings (step 13) — complete Getting Started — Recommended Setup Sequence steps 1–12 first. Requires Tenants module permission (tenants.module). After go-live, pair With Debt triage with Finance and Handling a Late Payment. Workflow pairing: Modules — Setup sequence after go-live.

Finding your way in this guide

Open Access Path and Interface overview for toolbar filters, then use Core Workflows — especially With Debt triage paired with Finance. Segment with tenant category filter like Bookings and Finance. Guide subsection map: Tenants guide subsection index (directory, profile, and segment sections + Related subsections). Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Finance Income status drill-down, Cash flow forecast drill-down, Reject/revert mistaken receipts, Partly collected security deposit, Wrong tenant on a booking, Cancel Booking vs Delete Booking, Portfolio segmentation by tenant category) have matching Related subsections below. Full pairing matrix: Tenants section cross-reference · Modules — Module cross-reference.

The Tenants module gives your team a tenant-first workspace for day-to-day follow-up. Instead of starting from a booking, you can search and segment your full tenant base, open a tenant profile, and review bookings, payment plans, and transaction history from one place.

Pair with other modules

Jump to reservations in Bookings; triage With Debt in Finance Contract Values. During month-end With Debt triage alongside Portfolio KPI review — Step 7, poll AI usage API (landlord_chat) when teams leaned on AI Chat for debtor lookups — there is no in-app ledger screen yet. Section-to-doc pairing: Tenants section cross-reference. Hub tab matrix: Modules — Module cross-reference.

Access Path

Sidebar path: Portfolio > Tenants
Route: /tenants
Direct link: platform.vivin.app/tenants

In the current product navigation, the Tenants sidebar entry is grouped with Listings and Bookings in the Portfolio section. See Deep Links for all management frontend routes.

Opening a tenant by URL

Append the tenant UUID to open the profile sidebar directly, for example /tenants/<tenantId>. If the id does not exist or is outside your account scope, the app shows Tenant not found., clears the bad segment, and returns you to /tenants — see Deep Links — Broken entity deep links.

What You Can Do in the Tenants Module

The module opens on a list/grid of tenant records with fast filtering and search:

Search by tenant name, email, phone, fiscal ID (NIF / VAT), or identification ID — the directory haystack matches any of these fields server-side (accent-insensitive substring match). A query that spans first and last name (for example Tim Trompa) matches the concatenated full name, not only each column separately.
Segment by status: All, Active, Inactive, With Debt, No Bookings
Sort in table view via column headers (Name, Phone, Total, Balance, Status)
Export the current directory slice as Tenants CSV or Bookings CSV (same filters, search, sort, and status segment as the on-screen list)

Directory loading (infinite scroll)

The tenant directory is server-paged in both grid and table views. The first request loads a batch of rows; as you scroll near the bottom of the page, the app loads the next batch automatically (skeleton placeholders appear while fetching). When every tenant matching your current search, status segment, and sort is loaded, an End of list line appears. Changing any of those controls resets the list and starts from the first batch again — exports always reflect the full filtered result set, not only the rows currently on screen.

Load failures — When the first directory request fails, the page shows a red inline alert card — Failed to load tenants. Please try again. — with optional server detail and Retry instead of an empty grid or table. A successful fetch with no matching tenants is the normal empty state. See Glossary — Directory list load failures.

While the next batch loads, compact skeleton cards (grid) or table skeleton rows (table view) appear at the bottom of the directory:

Tenants — grid directory loading the next page with skeleton placeholder cards at the bottom

Tenants — directory scrolled to the end with the End of list marker (search narrowed to a clean example tenant)

Selecting a tenant opens a detail sidebar with dedicated tabs:

Tenant Info — personal details, billing details, bank details, and Category (when tenant categories exist)
Bookings — all bookings linked to that tenant
Payments — payment plan context from the tenant's bookings
Transactions — received payments and allocation history

Core Workflows

Pair with other Tenants sections

With Debt triage pairs with Finance module and Handling a Late Payment — create profiles via Create New menu — Tenant. Full pairing matrix: Tenants section cross-reference.

1) Prioritize Collections and Follow-up

Use the With Debt filter to quickly identify tenants whose net balance is negative (they still owe money across linked bookings). Open each tenant to validate booking context, then coordinate with the Finance module for payment reconciliation.

2) Review Tenant Activity Across Multiple Bookings

Use a single tenant profile to review active and historical bookings without opening each reservation from the bookings table.

3) Maintain Tenant Master Data

Open Tenant Info to update personal/contact details, assign a tenant category (portal and field rules), and maintain billing information used by downstream finance workflows. Saving a new Category back-syncs booking.tenantCategoryId on linked reservations and force-refreshes Finance caches (#2088) — Contract Values, Overview, and Deposits Tenant category filters typically reflect the segment within seconds; see Glossary — Finance tenant category cache refresh.

Use + Create New → Tenant when you need a tenant record before a booking exists (for example a direct enquiry). The modal collects required identity fields and an optional tenant category:

Tenants — Add tenant modal from Create New with sample identity fields (not submitted)

On Tenant Info, click the pencil icon on Personal Information to enter edit mode — category, contact fields, and email-change rules appear inline:

Tenants — Tenant Info edit mode with personal fields and category selector (example tenant Luisa Köster)

4) Investigate Payment Status with Context

Use Payments and Transactions tabs to understand what is scheduled versus what has been paid, then jump into Bookings for contract-level actions when needed.

Permissions and Access

Tenant visibility and editability depend on role permissions:

Accessing the Tenants module (sidebar entry + /tenants route) requires Tenants module permission (tenants.module).
Creating or updating tenant records requires tenants.create permission (in addition to tenants.module).
The Bookings tab depends on Bookings module permission (bookings.module).
The Payments tab depends on Bookings module permission (bookings.module).
The Transactions tab depends on Finance module permission (finance.module).

Review and adjust role access in Settings > Users.

Interface overview

Pair with other Tenants sections

Tenant category filter pairs with Bookings — Other filters tenant category and Finance — Tenant category filter — bookmark searches with Deep Links — Tenants ?q=. Full pairing matrix: Tenants section cross-reference.

The Tenants screen combines a toolbar (search, tenant category filter, status filters, sort, view toggle between grid and table, export) with a tenant directory. Status pills (All, Active, Inactive, With Debt, No Bookings) show live counts from the server; pick a segment before you sort or export so the file matches the slice you reviewed.

Tenants — grid directory with status pills (All, Active, Inactive, With Debt, No Bookings) and toolbar

When your account has at least one tenant category configured, the toolbar includes an All categories dropdown (desktop). Pick one or more segments to narrow the directory to tenants assigned that category on Tenant Info, or choose No category for profiles with no segment. The menu stays open while you add selections (same compact pattern as Bookings — Select categories). Search, status pills, sort, grid vs table, and Export all respect the filter server-side — downloads reflect the full filtered population, not only rows already loaded by infinite scroll.

Tenants — toolbar tenant category filter with one segment active and narrowed directory

Tenant category filter capture refreshed 2026-06-27 23:04 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL VIVIN_DOCS_TENANT_CATEGORY_SEARCH="Teste Jorge" npx tsx tools/capture-bookings-tenants-tenant-category-filter-screenshots.ts).

Screenshot freshness

Status pills, Add tenant modal, and Tenant Info edit mode captures refreshed 2026-06-16 11:06 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-tenants-screenshots.ts).

Use Search when you want a tight view of one tenant or a small set of matches — especially helpful in busy directories where the default sort can surface mixed or internal test labels at the top of the list. Paste a fiscal ID or ID number when collections or onboarding paperwork references the tax id instead of the tenant’s display name.

Fiscal ID search capture refreshed 2026-06-12 00:05 UTC (npx tsx tools/capture-tenants-fiscal-id-search-screenshot.ts). The same haystack also matches identification ID — see Glossary — Directory search ranking.

Bookmarkable search (`?q=`)

The toolbar Search field syncs to the URL query parameter q. Share or bookmark a filtered directory view, for example platform.vivin.app/tenants?q=smith.

On load, back, or forward navigation, the input hydrates from ?q= so bookmarked or shared links land on the same filtered list.
As you type, the URL updates after a short debounce (~250ms) with replace so history does not stack one entry per keystroke.
Clearing the search removes q from the URL.
Status pills, sort, and grid vs table stay in component state only — they are not encoded in the URL today.
The directory API request debounces separately (~1s) so typing stays responsive while the server catches up.

Tenants — list with toolbar Search pre-filled from /tenants?q= with filtered rows visible after load

Grid card anatomy (dense directory view)

In grid view, each tenant card is a self-contained summary — useful for collections and multi-booking follow-up without opening the full profile first.

Region	What it shows
Header (clickable)	Avatar, name, Active / Inactive pill, email, phone, nationality flag — opens the tenant detail sidebar (`/tenants/<id>`).
Balance strip	Roll-up Balance (net financial position across linked bookings). Shown only when balance ≠ 0 — red when the tenant owes money, teal when credit remains.
Booking groups	Reservations grouped by status — Ongoing, Upcoming, Ended, Cancelled, Refunded — with up to two rows per group before collapse.
Per-booking rent / balance	Each preview row shows rent on the right; when a booking has negative financial balance, a red amount appears under rent (same rules as Bookings).
Show all bookings / Show less	Expands the card when a tenant has more bookings than the preview limit.
Booking row click	Opens the booking sidebar in place (contract-level context) without navigating away from the directory.

When a tenant has more bookings in a status group than the preview limit (two rows per group), the card stays collapsed until you click Show all bookings. Show all bookings reveals every row in that card; Show less returns to the preview limit so dense directories stay scannable.

Click any booking row (not the tenant header) to open the booking sidebar while staying on /tenants — useful when you are triaging debt on the card and need contract or payment context without losing your filter.

Tenants — grid card expanded with Show all bookings revealing additional reservation rows

Use table view when you need column sort and dense scanning; use grid when debt and booking mix matter at a glance. Cross-module triage: Handling a Late Payment (With Debt + expand), Glossary — Tenants table expand, Deep Links — Tenants.

Table view (expandable booking rows)

In table view, each tenant occupies one summary row. Sort by Name, Phone, Total, Balance (net roll-up), or Status using the column headers. Wider breakpoints also show Nationality, a compact Bookings breakdown (coloured chips such as on / up / en / ca for ongoing, upcoming, ended, and cancelled counts), and Category.

Action	Result
Click the row (chevron area)	Expand or collapse an inline sub-table of that tenant’s linked bookings.
Click the tenant name	Open the tenant detail sidebar (`/tenants/<id>`) without leaving the directory.
Click a booking sub-row	Open the booking sidebar in place (same pattern as grid cards).

When expanded, a header row labels the sub-table columns:

Column (English UI)	What it shows
Unit	Listing internal name for the reservation.
Rent	Contract rent for that booking.
Created	Booking creation date (when the viewport is wide enough).
Status	Booking status badge (Ongoing, Upcoming, etc.).
Period	Contract / move-in window for the stay.
Balance	Current booking balance from the same rules as Bookings — red when the tenant owes money, teal when credit remains, em dash when settled.
Src	Sales platform icon (channel source).
CT	Contract signed indicator (check vs dash icon with tooltip).

Tenants with no linked bookings show an italic No bookings line when you expand the row.

Tenants — table view with one row expanded showing Unit / Rent / Balance booking sub-table

Table expand capture refreshed 2026-06-20 19:08 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-tenants-table-expanded-screenshots.ts — search Köster, expand first clean row with bookings).

Walkthrough: switch to table view, narrow with Search, expand a tenant row to the booking sub-table, open the tenant name sidebar, then collapse the row.

Export (Tenants CSV / Bookings CSV)

Use Export on the toolbar when you need a spreadsheet of the same slice you are reviewing (status pills, Search, sort, and grid vs table view all apply server-side).

Open Export, then choose:

Option	File
Tenants CSV	One row per tenant in the current result set (directory fields).
Bookings CSV	Booking rows linked to tenants in that same filtered directory view.

Downloads use dated filenames from the API. If the filtered list is empty, the export action does not produce a file.

When the export API returns an error (for example HTTP 400/500), Vivin shows a toast (Export failed.) instead of leaving the menu closed with no file — narrow filters or retry after connectivity improves. See Glossary — Export and download failures. The Bookings list uses an inline alert under the toolbar for the same class of failure.

Walkthrough: status pills (All, With Debt, Active), narrow with Search, switch grid / table, then open a tenant sidebar on a clean example row.

Click a tenant card header, a table row name, or use Edit flows from the directory to open the detail sidebar on the right. (In table view, clicking the row body expands bookings inline — use the name link for the profile sidebar.) The URL updates to /tenants/<tenant-id> so you can bookmark or share a profile (subject to the same Tenants module permission). The sidebar header shows the tenant name and status; close it with the X control or by navigating back to /tenants.

Tab	What you see
Tenant Info	Personal Information, Billing Information, and Bank Details in one scrollable view (grid layout aligned with the booking sidebar). Each section has its own pencil edit control when your role includes `tenants.create`.
Bookings	All reservations linked to this tenant (requires Bookings module).
Payments	Payment-plan context aggregated from those bookings (requires Bookings module).
Transactions	Received payments and allocation history (requires Finance module).

Tenants — detail sidebar on Tenant Info with personal and billing sections

Tenants — detail sidebar Bookings tab listing linked reservations

Payments aggregates scheduled charges from every booking linked to the tenant (status pills, totals, and per-booking breakdowns when data exists):

Tenants — detail sidebar Payments tab with scheduled charges across linked bookings

Transactions lists received payments and allocation history pulled from those bookings (filters for in/out payment types when transactions exist). Manual receipts may still show as pending until someone with Approve payments confirms them on Finance → Transactions or the booking Transactions tab — the tenant-level roll-up can look settled while Pending rows still exist on the ledger (the Overview Manual Payments KPI includes approved manual receipts too). Reject payment, bulk Reject selected, and Revert payment modals warn about credit notes when Finance may already have invoiced the charge — see Payment Allocation — Correcting mistaken receipts. See Finance — Pending manual payments.

Tenants — detail sidebar Transactions tab with received payments and allocation summary

From Bookings or Transactions, use in-sidebar links to jump into the Bookings module when you need contract-level actions (including per-row Approve payment when a receipt is still pending).