Tenant categories

Tenant categories let operators define segments of tenants with shared rules for the Tenant Portal, profile fields, communications, and booking behaviour. This tab is separate from Categories (listing tags, booking tags, ticket types, and similar chip catalogs).

Open Account Settings → Property → Tenant categories at /settings/tenantCategories. The tab uses the same Categories permission as the chip-based Categories tab (account_settings.categories).

First-time workspace setup

Complete Getting Started — Recommended Setup Sequence step 10 (this tab — portal segments and default for integrations) after step 9 Categories and before step 11 Emails — full tab map: Recommended setup order. Set default for integrations before high-volume Integrations imports in step 12. Finish steps 13–15 in Listings, Bookings, and Tenants, then Onboarding a New Property — Step 7. Guided steps 4–12: Onboarding a New Property. Lockout catch-up: Getting Started. Workflow pairing after go-live: Account Settings — Setup sequence after go-live.

Finding your way in this guide

Understand What tenant categories control, then walk through Key workflow: edit a category. Set default for integrations before bulk imports — see How categories are used in the product. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, 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) have matching Related subsections below. Full pairing matrix: Tenant categories section cross-reference · Account Settings — Tab cross-reference.

Pair with other Account Settings tabs

Direct bookings do not auto-assign a segment — operators assign Category on Tenants → Tenant Info per FAQ — Assign tenant category for direct booking. Align segment portal modules with Preferences account-wide defaults, and set default for integrations before bulk Integrations imports. Distinct from listing/booking chip catalogs on Categories. AI usage is account-scoped, not segment-scoped — when chat or utility AI activity clusters on one cohort, pair segment filters on Bookings — Other filters with AI usage API during Portfolio KPI review. Section-to-doc pairing: Tenant categories section cross-reference. Hub tab matrix: Account Settings — Tab cross-reference.

What tenant categories control

Pair with other Tenant categories sections

Top toggles and portal modules here override account Preferences — Tenant Portal defaults per segment — define segments before Integrations bulk imports assign default for integrations. Full pairing matrix: Tenant categories section cross-reference.

Each category has a name and optional rules in three areas:

Area	Purpose
Top toggles	Communications / Email (tenant lifecycle emails for this segment), Multiple concurrent bookings, and Tenant Portal Access (master switch for portal login and modules).
Tenant portal fields	Which profile fields tenants may view or edit in the portal (name, ID documents, billing, bank details, and related fields). Only applies when Tenant Portal Access is on.
Tenant portal modules	Which portal areas are available: documents/invoices, support/chat, payment plan, VIVIN payments (card / vIBAN), contract, subscriptions/extras, and utilities. Hidden when portal access is off. Disabling Contract (or turning off Tenant Portal Access, which forces every module off) also prevents Vivin from attaching the contract PDF to the onboarding email, even when Preferences → Contract in onboarding email is on.

When Tenant Portal Access is turned off for a category, the product clears portal field and module toggles on save so stored rules stay consistent (the editor shows a hint that fields below are not applicable).

Default for integration-created tenants

One category can be marked Default for integration-created tenants. New tenants created by allowlisted booking integrations receive that category when they arrive without an existing assignment. If no default is set, the UI shows a warning that integration-created tenants will not be auto-assigned.

Assign categories manually on Tenants (Tenant Info tab) or when creating a tenant from + Create New — see Processing a New Booking — Step 2 for direct reservations. The Add booking wizard does not set category; assign on the profile before contract or onboarding mail.

Communication Rules audience — When categories exist, Settings → Emails → Communication Rules can scope automated tenant messages by Tenant categories using the same No filter / Include only / Exclude pattern as smart-lock and booking-tag filters. See Emails — Audience filters.

Interface overview

Pair with other Tenant categories sections

List load failures surface as toasts — see Glossary — Settings and profile load failures before assuming no segments exist. Full pairing matrix: Tenant categories section cross-reference.

The tab lists existing categories with Default for integrations badge when applicable. Use Add category to create a row, or Edit / Delete on an existing category.

Load failures — When the category list cannot load, Vivin shows an error toast (Failed to load tenant categories.) instead of an empty list. Refresh the tab or reopen Account Settings → Tenant categories after connectivity recovers. See Glossary — Settings and profile load failures.

Account Settings — Tenant categories list with Add category and default-for-integrations badge

Screenshot freshness

List, editor, portal-access-off, and delete-confirm captures refreshed 2026-06-16 16:05 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-tenant-categories-screenshots.ts). No-default-for-integrations banner skipped — docs account already has a default segment.

The editor modal groups name, the default for integrations toggle, top module toggles, then Tenant portal fields and Tenant portal modules sections.

Account Settings — Tenant category editor with portal access, field rules, and portal module toggles

Warnings and editor states

Pair with other Tenant categories sections

The no default for integrations banner should be cleared before Onboarding a New Property channel steps — unassigned integration tenants break Emails audience filters. Full pairing matrix: Tenant categories section cross-reference.

Operators hit a few states that are easy to miss in a quick tour of the list:

State	What you see	What to do
No default for integrations	Amber banner under the category list when no row holds Default for integration-created tenants	Pick one segment and turn on the default toggle before high-volume channel onboarding — otherwise integration-created tenants stay unassigned.
Tenant Portal Access off	In the editor, the Tenant portal fields and Tenant portal modules sections disappear and an amber hint explains they are not applicable	Expected when a segment should not log into the portal at all; portal rules are cleared on Save.
Delete category	Danger Confirm modal naming the segment	Only delete unused segments — tenants already assigned keep their category until you change them on Tenants.

When no category is marked default for integrations, the list shows an amber banner under the rows (integration-created tenants will not auto-assign):

Account Settings — Tenant categories list with amber no-default-for-integrations warning

Turn Tenant Portal Access off in the editor to preview how field and module toggles hide (rules clear on save):

Account Settings — Tenant category editor with Tenant Portal Access off and amber portal hint

Delete on a row opens a confirmation step — cancel if you opened it by mistake:

Account Settings — Delete tenant category confirmation modal

Key workflow: edit a category

Pair with other Tenant categories sections

After Save, verify portal behaviour on a pilot tenant in Tenants before rolling segment rules to production imports — Managing a Check-in assumes portal modules match the segment. Full pairing matrix: Tenant categories section cross-reference.

Open Account Settings → Property → Tenant categories.
Click Add category for a new segment, or Edit (pencil) on an existing row.
Set the name and, when needed, mark Default for integration-created tenants (only one category can hold that flag).
Use the top toggles for Communications / Email, Multiple concurrent bookings, and Tenant Portal Access. Turning Tenant Portal Access off hides Tenant portal fields and Tenant portal modules in the editor and clears those rules on save.
When portal access is on, enable the profile fields and portal modules that match the segment (for example hide VIVIN payments for corporate tenants who pay offline).
Click Save to persist, or Cancel to close without changes.

Walkthrough: open Edit on a category, toggle Tenant Portal Access off and on to show how field and module sections appear, scroll the modal, then Cancel without saving.

How categories are used in the product

Pair with other Tenant categories sections

Bookings, Finance, and Tenants share the same Tenant category filter semantics — scope one segment in Finance — Tenant category filter during month-end before account-wide portal changes. Full pairing matrix: Tenant categories section cross-reference.

Tenants — Tenant Info includes a Category control when categories exist; operators pick the segment for that person. The directory toolbar All categories filter narrows /tenants by assigned segment (see Tenants — Tenant category filter).
Bookings — Other filters → Tenant → Tenant category limits the portfolio to reservations whose tenant profile carries the selected segment(s), with No tenant category for unassigned tenants (same OR-combined server filter as nationality and booking tags). Assign category on direct bookings in Processing a New Booking — Step 2 before contract mail. During month-end review, pair with Portfolio KPI review — Step 6 when Analytics ranking suggests one segment underperforms.
Finance — Other filters → Tenant → Tenant category applies the same segment filter server-side on Overview, Income, Contract Values, Transactions, Deposits, and Payouts — use it when reconciling Debt Aging, Contract Values In Debt, or deposit queues for one tenant segment without exporting the whole portfolio. Deposit pill states (Ready to Refund, Disputed) are defined in Glossary — Deposit lifecycle status. See Finance — Tenant category filter. Changing Category on Tenant Info force-refreshes Finance caches so filter results catch up within seconds (#2088) — Glossary — Finance tenant category cache refresh.
Tenant Portal — Portal modules and field visibility follow the tenant’s category rules (for example hiding VIVIN payments or Contract for a segment).
Emails — Category module rules (for example portal or payments visibility) still shape what tenants see and what system templates include, but operator-authored Email body text does not support Handlebars/{{#if …}} conditionals such as show_tenant_portal_section — use the Variables catalogue and category toggles instead (#1208). Communication Rules can also scope automated messages by tenant category — see Audience filters. Before enabling a scoped rule, cross-check audience size on Bookings, Finance, or Tenants.
Integrations — Inbound bookings from configured channels can auto-assign the default for integrations category to new tenants.

Best practices

Create a small set of clear segment names (for example Standard resident, Corporate, Short-stay) before rolling portal restrictions to production tenants.
Turn off Communications / Email only when you intentionally want lifecycle emails suppressed for that segment (new categories default this toggle off; existing rows follow stored values).
Set the default for integrations category before high-volume channel onboarding so new tenants inherit the right portal and field rules on day one.

Tenant categories section cross-reference

Use this table when one Tenant categories topic naturally leads into another Account Settings tab, operator module, workflow, or concept — each row links to the docs you should read before or after saving segment rules.