Utilities

First-time workspace setup

Enable utility types under Invoicing & Payments — Utilities (setup step 7) and finish Listings (step 13) before supplier billing here — see Getting Started — Utilities & Bills Included (optional) and Entering Monthly Utility Bills. Workflow pairing: Modules — Setup sequence after go-live.

Finding your way in this guide

Scope with Portfolio scoping (Select properties), then Overview tab for KPIs. Supplier setup: Connections tab → Bills tab entry workflow → Cost map tab and Allocations tab for tenant charges. Guide subsection map: Utilities guide subsection index (tab sections + Related subsections). Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, 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, Partly collected security deposit, Portfolio segmentation by tenant category) have matching Related subsections below. Full pairing matrix: Utilities section cross-reference · Modules — Module cross-reference.

The Utilities module tracks and manages monthly property expenses for electricity, water, gas, and internet.

Direct access

Open the Utilities module at platform.vivin.app/utilities. Tab routes include /utilities (Overview, default), /utilities/connections, /utilities/bills, /utilities/timeline, /utilities/cost-map, and /utilities/allocations. Legacy paths /utilities/overview and /utilities/properties redirect to /utilities. Unknown tab slugs also normalise to /utilities. See Deep Links for the full route table.

Pair with other modules

Configure Bills Included ceilings in Listings Step 3; charge tenant overages through Bookings Payment plan and reconcile in Finance. When approved overage lines pass due date without pay-in, payment overdue alerts row-click into the booking — continue with Handling a Late Payment — Step 1. When overages cluster on one tenant category, scope Finance — Tenant category filter (Step 4 of Entering Monthly Utility Bills) — mirror Bookings — Other filters tenant category or Tenants — Tenant category filter when Finance cache parity lags. Section-to-doc pairing: Utilities section cross-reference. Hub tab matrix: Modules — Module cross-reference.

Its primary purpose is threefold: giving you a clear view of your utility costs across your entire portfolio, automatically reading utility bills using AI, and automatically calculating the tenant overage (the portion of a utility bill that exceeds the included amount and is charged back to the tenant).

Portfolio scoping (Select properties)

Most Utilities tabs expose Select properties in the header (desktop) or tab toolbar. The control is a multi-select server-driven search picker: opening the menu prefetches about 10 buildings, typing runs debounced server search, and scrolling near the bottom loads the next page — the same paged pattern as Finance → Other filters → Property and Sales → Pricing. With an active query, internalName matches rank above address-only hits before pagination — see Glossary — Picker search ranking.

Current builds (June 2026 performance pass) use that picker for Utilities instead of downloading the legacy bulk GET /properties list on every cold load — the menu pages through GET /properties/search (prefetch ~10, debounced query, infinite scroll). Selected buildings appear as removable chips; Clear all resets scope on tabs that show the chip row (for example Cost map and Connections).

Screenshot freshness

Select properties picker capture refreshed 2026-06-13 01:12 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL VIVIN_DOCS_PROPERTY_SEARCH=AA-11-5D npx tsx tools/capture-utilities-property-picker-screenshot.ts).

Select properties search-ranking capture refreshed 2026-06-17 17:05 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL VIVIN_DOCS_PROPERTY_SEARCH=António npx tsx tools/capture-utilities-select-properties-picker-search-rank-screenshot.ts).

Tabs that honour the same selection include Overview (desktop header), Connections, Bills, Timeline, Cost map, and Allocations — narrow scope before exporting grids or interpreting Cost map colouring on large portfolios.

Tab load failures

Each Utilities tab loads its own API slice. A failure on one tab does not block the others — switch tabs or use Retry (where shown) after connectivity recovers.

Tab	How the failure appears	Recovery
Overview	Red alert card — Failed to load overview data. Please try again.	Retry on the card
Connections	Red alert card — Failed to load connections. Please try again. (optional server detail line)	Retry
Bills	Red alert card — Failed to load bills. Please try again. (optional server detail line)	Retry
Timeline	Red alert card — Failed to load bills. Please try again.	Retry
Cost map	Red alert card — Failed to load data.	Refresh the browser tab or leave and reopen Cost map (no Retry control on this tab today)
Allocations	Red alert card — Failed to load bill allocations. Please try again.	Retry

Screenshot freshness

Tab load-failure captures re-verified 2026-06-17 07:12 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-tab-load-failures.ts). Overview, Connections, Bills, and Allocations PNGs saved. Cost map failure PNG remains follow-up — useCostMap stays on skeleton when GET /bills/cost-map is blocked on cold load or property-scope refetch in headless capture (no Retry control on that tab today).

A successful fetch that returns no rows for your filters is not this state — that is the normal empty state (for example Timeline before any bills exist). See Glossary — Directory list load failures.

How Utility Billing Works

Vivin uses a ceiling model for tenant utility billing. When you create a property, you define a Bills Included amount for each utility — the maximum cost that is absorbed into the rent. If the actual monthly bill exceeds that ceiling, the tenant is automatically charged the difference.

Example

• Bills Included (electricity) on a property: €50/month
• Actual electricity bill for March: €73
• Tenant overage charge: €23 (added to their payment schedule)
• If the bill had been €42, the tenant pays nothing extra — you absorb the full €42

For this system to work, two things must be set up:

1. Utility account IDs linked to each property (configured in the property wizard Step 2, managed in the Connections tab)
2. Bills Included amounts configured on the property (Step 3 of the property wizard)

Overview tab

Pair with other Utilities sections

Overview pairs with Dashboard and the monthly rhythm in Entering Monthly Utility Bills — segment gaps with Finance — Tenant category filter. Full pairing matrix: Utilities section cross-reference.

The Overview tab is the central dashboard for utility expenses across your entire portfolio. It loads with the current month selected, and you can navigate to any past month using the month selector.

The overview shows a list of all utility bills for the selected period. For each entry you can see the property, utility type, billing amount, and whether the bill has been paid or is still outstanding.

Below the list, the tab includes two key charts:

Total Expense Value Over Time A stacked bar chart showing utility costs month by month. Each bar is segmented by utility type (electricity, gas, water, internet), each in a distinct color. This lets you:

• Identify seasonal cost spikes (e.g., higher gas bills in winter)
• Spot sudden increases that may indicate a leak or equipment fault
• Track whether your overall utility spend is trending up or down

Days Missing Data by Utility Type A stacked bar chart showing how many days of bill data are missing for each utility type in each month. Missing data gaps mean the system cannot calculate accurate tenant overages for those periods. Use this chart to identify which properties need bills entered for past months.

Filter by property (desktop)

There is no separate “Properties” sub-tab. Legacy URLs /utilities/properties and /utilities/overview redirect to Overview (/utilities).

On desktop, use Select properties in the Overview header (next to the month / date-range control) to limit the bill list and charts to one or more buildings. The picker uses the paged server search pattern — you do not need every property loaded before you can filter. That scoped view is what you use when you want a property-by-property read of costs, connections context, and bill history without leaving Overview.

Use a scoped Overview when reviewing a property’s operational costs or preparing an owner statement — it is the single place to see monthly utility costs, which account IDs apply, and bills entered for that slice of the portfolio.

Load failures — When the Overview bill list cannot load, the tab shows Failed to load overview data. Please try again. with Retry instead of empty charts. See Tab load failures.

Connections tab

The Connections tab (/utilities/connections) is a property × utility contract-ID matrix. Each row is one property; columns are Electricity, Water, Gas, and Internet contract IDs. Use it to view or maintain the configuration layer that tells Vivin which utility account belongs to which building — the same IDs you can seed in Step 2 of the property wizard.

Connections grid captures refreshed 2026-06-16 07:08 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-connections-grid-screenshots.ts).

Grid layout and permissions

Element	Behaviour
Property (sticky left column)	Internal property label for each row
Utility columns	One contract ID cell per service
Read-only	Users without utilities.edit_connections see the full matrix but an amber banner explains they cannot edit — ask an administrator to enable Utilities → Edit connections in Role Permissions
Search	Filters rows by property name
Select properties	Multi-select server-driven picker — chips + Clear all on tabs that show the chip row
Export	CSV or Excel for rows currently loaded in the filtered grid

Contract IDs are first set in Step 2 of property creation; update them here when a provider changes references without reopening the property editor.

SIMAR water (Loures e Odivelas) — #2110

SIMAR water bills use Cód. Local / Código de Local from the supplier PDF — not Nº de Contador. Strip leading zeros before you save (for example 0181474 → 181474). EPAL follows a similar Código de Local rule; SIMAS and most other operators still use the meter number. See Glossary — SIMAR water contract ID and FAQ — SIMAR water bill property match.

When two or more properties use the same contract ID for a utility type (one physical meter or supplier account serving multiple buildings), Vivin treats that as a shared connection. Timeline and Cost map attribute daily utility intensity across every property tied to that ID — not only the row you happened to filter. Keep sibling properties on the same contract ID aligned in this grid before you interpret Cost map colouring or Allocations rows for a subset of the portfolio.

Editing a cell (inline)

Users with Edit connections permission:

1. Click a cell (or No connection) to enter inline edit mode.
2. Type the contract ID (meter number, customer reference, or similar).
3. Save with the check control or Enter; Cancel with ✕ or Escape.

While editing, a small on/off toggle beside the input reflects whether the cell has a value.

Marking a utility as not applicable (N/A)

Each cell has an on/off toggle in read mode:

• On (teal) — a contract ID is saved; click the toggle to turn off and persist N/A when that utility does not apply to the property.
• Off (grey) — empty or N/A; shows No connection. Click the toggle to turn on and open edit mode for a new ID.

Once a valid ID is saved, bill imports and manual Bills entries can match the property automatically.

Scrolling and large portfolios

The grid windows property rows client-side for performance: an initial batch of about 30 properties renders first, then about 5 more rows load as you scroll (skeleton rows at the bottom). A footer shows Showing X of Y connections for the current Search and Select properties scope. Changing search or property chips resets from the first batch.

Narrow before export on large portfolios

On accounts with hundreds of properties, the default unfiltered grid may mix internal test labels with production rows in the first loaded batch. Use Search connections (property code or name) or Select properties to scope the grid to the buildings you care about, then scroll and Export — the download always reflects loaded rows only, not the server total in the footer.

When the filtered slice is larger than the first batch, the footer shows how many rows are on screen versus the server total (for example Showing 30 of 103 connections after scoping with Search connections):

Export includes only loaded rows — scroll until the footer shows every connection you expect before downloading a full portfolio extract (or narrow with Search / Select properties first so each batch is meaningful).

Load failures — When the connections matrix cannot load, the tab shows Failed to load connections. Please try again. with Retry (and optional server detail). See Tab load failures.

Business Rule

If a property has no connection (or N/A) for a utility type, the system cannot associate bills for that service with the building. Ensure every active utility you bill for has a real contract ID, or mark irrelevant services N/A explicitly.

Bills tab

Pair with other Utilities sections

Bills pairs with Automation & AI — AI invoice reader, Entering Monthly Utility Bills — Step 2, and AI usage API (utility_bill_extraction on GET /ai-usage/summary when you monitor PDF extraction volume at month-end) — scope with Select properties before bulk actions. Full pairing matrix: Utilities section cross-reference.

The Bills tab is the detailed ledger of every utility bill entered into the system. This is where day-to-day bill management happens.

Use Select properties in the tab toolbar when you enter or audit bills for one building at a time — the same paged picker scopes Received, Missing, and bulk Download selected / Delete selected actions. See Entering Monthly Utility Bills for the monthly operator rhythm.

On desktop, the tab bar includes an Add Bill shortcut in the header row (same entry point as in-tab controls). Inside the tab, use the Received / Missing toggles: Received is the main bill ledger; Missing lists simulated gaps from billing history so you can chase bills before overage math drifts.

Switch to Missing when you want a proactive gap list instead of scrolling the Overview Days Missing Data chart. Vivin simulates expected billing periods from your Connections history and flags rows where no Received bill exists yet. Each row shows the property, utility type, expected period, estimated amount, and days overdue (with an OVERDUE badge when the gap exceeds your account deadline). Use Add Bill from a row or the header shortcut to enter the missing statement.

Missing-toggle capture refreshed 2026-06-11 12:06 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-bills-missing-tab.ts).

Each bill entry shows:

Column	Description
Property	Which property this bill belongs to
Utility Type	Electricity, Gas, Water, or Internet
Billing Period	The month or date range this bill covers
Amount	The total billed amount
Status	Paid, Unpaid, or Overdue

Filtering Bills

Use the filter controls above the list to narrow down by:

• Property — view bills for a single building
• Utility type — focus on one service (e.g., only electricity)
• Status — isolate unpaid or overdue bills that need action

Bulk selection (Received ledger)

On the Received ledger, use the row checkboxes (or the header checkbox to select every row currently visible in the table) to act on multiple bills at once. When at least one row is selected, a floating bar appears at the bottom of the workspace:

Control	Purpose
N selected	Count of checked rows in the current view.
Clear	Unchecks every selected row without changing bill data.
Delete selected	Opens a confirmation modal, then permanently removes the chosen bills. Deletion cannot be undone — prefer narrow Property / date filters before bulk delete on shared workspaces.
Download selected	Downloads a PDF for each selected bill that has an attached file. Rows without a stored PDF are skipped; when one or more downloads fail, Vivin shows a toast so you know the batch did not fully succeed — see Glossary — Export and download failures.

Bulk selection bar capture refreshed 2026-06-16 07:09 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-bills-bulk-selection-screenshot.ts).

Walkthrough: select two bill rows on the Received ledger, use Clear, re-select, open Delete selected, then Cancel (demo does not delete staging bills).

Bulk actions apply to the Received ledger only (not the Missing gap list). Header select all affects rows currently loaded in the table — scroll to load more pages before selecting a large portfolio slice, or narrow filters first so every target row is on screen.

Load failures — When the bill ledger cannot load, the tab shows Failed to load bills. Please try again. with Retry instead of an empty Received / Missing table. See Tab load failures.

AI Invoice Reader

Vivin includes an AI-powered invoice reader that automates the process of entering utility bills. Instead of manually typing in each bill's details, you can upload the bill document and the AI will:

• Automatically detect the utility type (water, electricity, gas, internet) from the document content.
• Identify the correct property and billing period without manual input, by matching account identifiers and addresses.
• Extract key data — provider name, billed amount, consumption values, and billing dates — directly from the document.

This eliminates the tedious and error-prone process of manual data entry, especially when processing dozens of bills across multiple properties each month.

From the Bills tab, use Add Bill (header shortcut on desktop) and stay on Upload to queue one or more PDFs; switch to Manual when you prefer typed fields or need to fix AI output. Vivin internal operators can also open + Create New > Tools > Upload Utility Bills from any screen — that opens the Upload Bills dialog (PDF-only batch upload) without the Manual tab on the same modal:

The Add Bill path in Utilities keeps Upload and Manual on one modal when you are already on the Bills ledger. Both entry points call the same extraction API; see Create New Menu > Tools.

Each successful PDF read is recorded in the account-scoped AI usage ledger as utility_bill_extraction — poll GET /ai-usage/summary (management JWT) when you reconcile adoption spikes during Portfolio KPI review — Step 7. There is no management-frontend screen for this ledger yet; costs are internal USD metering, not tenant invoices. See FAQ — How do I see AI token usage for my account?.

tip

For the AI Invoice Reader to match bills to properties automatically, ensure that your Connections tab has up-to-date account IDs for each property-utility pairing. The AI uses these identifiers to determine which property a bill belongs to. SIMAR (Loures e Odivelas) water PDFs must use Cód. Local in Connections — not the meter number (#2110); see Glossary — SIMAR water contract ID and FAQ — SIMAR water bill property match.

Adding a New Bill Manually

If you prefer to enter a bill manually (or the AI reader needs correction), click + Add Bill, open the Manual Entry tab, and fill in:

• Property — which property this bill is for
• Utility type — the service provider type
• Billing period — the month or date range the bill covers
• Amount — the billed amount (what you owe to the utility company)
• Due date — when the bill must be paid

Once saved, the system compares the bill amount against the Bills Included ceiling for that property and utility type. If the bill exceeds the ceiling, the system creates an overage charge in the relevant tenants' payment schedules automatically.

Business Rule

Bills must be entered for the correct billing period. An electricity bill covering March must have March as its period — if you enter it in April with April as the period, the overage calculation will be assigned to the wrong month and wrong tenants.

Timeline tab

The Timeline tab (/utilities/timeline) is a horizontal calendar grid: each row is a property (with utility coverage shown as coloured segments), and columns are days or weeks depending on zoom. It answers “where do we have bill coverage, and where are we blind?” at a glance.

Header tools (desktop)

• Search properties — narrows which property rows stay visible (matches property names).
• Select properties — same multi-select pattern as Overview: pick one or more buildings to scope the grid; combine with search when you have a large portfolio.
• Clear all — appears when search or property chips are active; removes filters in one click.
• Legend (next to the tab strip on wide screens) — Covered (green fill) means bill data is present for that slice of time; Today is a vertical marker; Deposit refund deadline is a separate marker used when the product highlights that cut-over in the header (useful when reconciling utility periods around move-outs).

Zoom

• Use Daily vs Weekly in the timeline toolbar to switch column granularity (the control is labelled Daily / Weekly in the UI).
• Today jumps the scroll position so the current date is in view after you have been exploring past or future months.

Walkthrough: switch Weekly / Daily zoom, recenter with Today, then narrow rows with Search properties.

Empty state

If there are no utility bills yet, the tab shows an empty state explaining that you need bills before timelines render—start from the Bills tab or your ingestion workflow, then return here.

When you open a bill PDF from the timeline grid and the file cannot be fetched, Vivin shows a toast instead of a blank preview — see Glossary — Export and download failures.

Property rows in the grid load in the same infinite-scroll batches as the Connections tab (about 30 properties first, then about 5 per scroll). Scroll vertically through a large portfolio to load additional rows before assuming every building is visible. Loaded rows are ordered by property internal name using natural numeric sort (same ordering as Listings unit lists).

Load failures — When the timeline grid cannot load, the tab shows Failed to load bills. Please try again. with Retry. See Tab load failures.

Cost map tab

Pair with other Utilities sections

Cost map pairs with Sales — Multicalendar for occupancy context and Listings — Bills Included ceilings. Full pairing matrix: Utilities section cross-reference.

The Cost map tab (/utilities/cost-map) maps daily utility intensity to listings (rooms/units) under each property. You get a wide matrix: properties and their units on the vertical axis, days on the horizontal axis, and cell colouring that reflects occupancy / booking context and whether utility cost could be attributed for that day.

The matrix is computed on the server (GET /bills/cost-map, cached per property selection) and fetched only when you open this tab — switching away from Cost map does not keep reloading the heavy join in the background. Expect a short skeleton while the first batch arrives; property/listing sidebars still load their own lightweight data for drill-through.

Load failures — When the cost-map request fails, the tab shows Failed to load data. in a red alert card. Refresh the page or reopen the tab — there is no Retry button on this tab today. See Tab load failures.

Legend (desktop, next to the tab strip)

• Mid-term — long-stay / coliving style occupancy colouring.
• Short-term — short-stay or channel-heavy stays (including iCal-style short-term where applicable).
• Manual block — operator-defined calendar blocks that affect occupancy display.
• Vacant — no qualifying stay on that day for that unit.
• No data — the cell cannot be coloured because underlying bill or mapping data is missing.

Cost map matrix capture refreshed 2026-06-22 01:20 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-cost-map-tab-matrix-screenshot.ts).

Walkthrough: open Timeline, switch to Cost map, then scroll the listing × day matrix to scan occupancy colouring and legend.

Property scope

Use Select properties in the tab header (when shown) to limit the matrix to specific buildings—especially important on accounts with many properties so the grid stays readable.

Shared utility connections warning

If your selection includes a property that shares a contract ID with another building you did not select, an amber banner appears above the matrix:

• Title: Shared utility connections detected
• Body: explains that cost allocation may be wrong while sibling properties stay out of scope
• List: each affected property, utility type, and the missing property names marked (not selected)

Shared-contract alert capture refreshed 2026-07-27 16:10 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-utilities-cost-map-shared-contract-alert.ts — select AA-15-RD-B alone so electricity sibling AA-15-RE_TU stays out of scope).

Walkthrough: on Cost map, open Select properties, choose one building that shares a utility contract, and read the amber Shared utility connections detected banner listing siblings still out of scope.

Add every property on that shared contract to Select properties (or clear the filter to load the full portfolio) before you rely on cell colouring or run Recalculate allocations. The same contract-ID sharing is visible on the Connections tab when multiple rows show identical IDs in a column. Month-end operators: see Entering Monthly Utility Bills — Step 3 when overage review starts on Overview but Cost map intensity still looks off for one building.

Recalculate allocations

The tab exposes Recalculate allocations (maintenance-style control). It calls the API to tear down and rebuild allocation rows, then reloads the page on success. Use only when you understand the impact on downstream Allocations and tenant charges; prefer normal bill corrections first.

Drill-through

Clicking relevant cells or rows can open the property or listing sidebars in place so you can adjust Listings settings (for example bills-included ceilings or unit context) without losing your place in Utilities.

Allocations tab

Pair with other Utilities sections

Allocations pairs with Bookings — Payment Plan tab and Entering Monthly Utility Bills — Step 4 — triage unpaid lines via Notifications — Payment overdue alerts. Full pairing matrix: Utilities section cross-reference.

The Allocations tab (/utilities/allocations) lists utility costs allocated to bookings with a status: pending review, approved (charged through the product’s “charged” state), or rejected. Use it to reconcile what the system proposes to bill tenants against what you expect from Finance and each booking’s payment plan.

Summary row (#2195)

Five clickable scope cards replace the legacy Status dropdown. Each card shows a count and currency total; click a card to filter the table to that lane (the active card gets a highlighted border). Hover the status pill on a card for a short tooltip.

Card	Meaning
Pending	Awaiting review — approvable or rejectable
Approved	Charged through the product (server state charged)
Rejected	Operator or Vivin rejected the proposed charge
Absorbed	Landlord-borne cost on a calendar block with no booking — read-only, never approvable or rejectable (grey badge)
Total allocated	All actionable + absorbed rows in the property-scoped summary

Summary counts vs the table

Card counts and euro totals come from a property-scoped server summary: they respect Select properties but do not change when you switch the active scope card, Booking status, Search, or Group by. That keeps card labels stable while you drill into the table — row counts and footer totals always match the active filter set. Absorbed rows are excluded from the Pending, Approved, and Rejected lane counts so bulk approve/reject cannot sweep them in by mistake.

Load failures

If the first allocations request fails, the tab shows a red alert card — Failed to load bill allocations. Please try again. — with Retry instead of an empty table. Summary cards and filters stay hidden until data loads. See Tab load failures and Glossary — Directory list load failures.

Loading more

The allocation table loads in batches of 30 rows. Scroll near the bottom of the list to fetch the next batch (a loading indicator appears while the request runs). Changing the active scope card, Booking status, Search, Group by, or Select properties reloads from the first batch.

Filters, grouping, and search

• Search — matches booking / property text in the allocation list (same debounced pattern as other modules), including the tenant’s concatenated full name when you paste first and last name together (for example Maria Silva).
• Scope cards — click Pending, Approved, Rejected, Absorbed, or Total allocated to filter the table (replaces the old Status dropdown).
• Group by — None (default flat list), Billing period, Property, or Tenant. Grouped sections collapse/expand; Group by and column sort are mutually exclusive — picking a group mode clears the active column sort arrow.
• Booking status — narrow by Ongoing, Upcoming, Ended, Cancelled, or Refunded stays.
• Select properties — portfolio scoping when the control is shown.
• Clear all — resets search, scope card (back to Total allocated), booking-status chips, grouping, and property selection in one action.

Sortable columns

When Group by is None, click column headers to sort server-side: Billing period, Property, Unit, Tenant, Booking status, Value, and Status. Sort direction toggles on repeat clicks.

Row details and drill-ins

Expand a row to see a per-utility breakdown (electricity, water, gas, internet), the bill total, the maximum allowed (bills-included ceiling context), days calculated, and the per-booking share. That breakdown is what operators use to validate a suggested charge before it hits tenant schedules.

In-page drill-ins — click the tenant name to open the booking sidebar; click unit or property cells to open the listing or property sidebar without leaving Utilities (#2195).

Bulk actions

When one or more pending rows are selected, Approve selected and Reject selected appear. Large selections are sent in chunks of 500 ids per request so very wide approve/reject passes do not fail on the server cap. When one or more approved (charged) rows are selected, Undo selected appears instead — you cannot mix pending and approved rows in one selection (#2196).

Undo approval returns mistaken approvals to pending without changing charges that are already invoiced:

Control	When it appears	What it does
Undo approval (row menu)	Approved scope card or table row in charged status	Opens a confirmation dialog, then moves that allocation back to pending.
Undo selected (bulk bar)	Multiple charged rows selected	Same as row undo; processes ids in chunks of 500 per request.

The confirmation copy shows how many allocations and the total € value will return to pending. Invoiced charges are untouched — if the tenant receipt was already invoiced, undo is blocked with "Cannot undo: the charge has already been invoiced." Bulk undo may partially succeed: the UI reports how many rows were undone, skipped (already invoiced/paid or no longer approved), or failed. Use Finance → Transactions → Reject or Revert when money already posted and you need a credit note instead of undoing the allocation row.

Who can undo approval

Undo approval and Undo selected follow the same Vivin internal gate as Approve / Reject — buttons stay visible but disabled for other roles.

Absorbed rows have no checkboxes or row actions. If an overage charge was already invoiced and you must remove a mistaken tenant receipt, Reject selected on Finance → Transactions (or Reject payment on the booking) shows the same credit note warning as other ledger actions — see Entering Monthly Utility Bills — Step 4b.

Who can approve or reject

Approve, Reject, and the matching bulk controls are enabled only for Vivin internal management users (the UI keeps the buttons visible but disabled for other roles). Customer Property Managers and similar roles can review allocations, filters, and breakdowns, but turning a pending row into an approved charge or a rejection is performed through Vivin operations unless your contract says otherwise. Use How it works in the tab header for the in-product explanation modal.

Help

Click How it works (question-mark control) to open the allocations explainer without leaving the page.

Pending scope card narrows the table to rows awaiting review (the table and footer totals update for that slice; summary card counts stay property-scoped):

Screenshot freshness

Allocations v2 scope cards, Group by, Absorbed lane, and drill-ins documented 2026-07-27 04:00 UTC (round 709, #2195). Existing PNGs predate the five-card toolbar — refresh utilities-allocations-tab-list.png and utilities-allocations-pending-filter.png when staging auth recovers.

Expand a row to inspect the per-utility breakdown (bill total, bills-included ceiling context, days calculated, and the booking share) before approving or rejecting:

How it works opens an in-page explainer modal (status lifecycle, who can approve, and how charges reach tenant schedules):

Walkthrough: Pending filter → expand a row for the utility breakdown → open How it works → close the modal (demo does not approve charges).

Smart Cost Distribution

Vivin supports flexible methods for distributing utility costs to tenants:

• By room — split costs equally across all occupied units in a property.
• By usage — allocate based on individual consumption data when sub-metering is available.
• By days of stay — prorate costs based on how many days each tenant occupied the unit during the billing period.

When Account Settings → Utilities → Charge Time is End of Booking, Vivin defers creating an allocation row for a stay until its check-out date has passed — but while that stay is still occupying a unit, it still counts toward how many rooms share each day’s overage (#2111). Example: two coliving rooms share one electricity bill; tenant A checks out in June while tenant B stays through August. March overage is split 50/50 across both rooms for every day both were occupied; tenant A’s charge posts only after A’s checkout, and tenant B’s share posts after B’s checkout — A is not charged for B’s remaining weeks. With Every Month, active bookings receive their share during the billing month instead. See Glossary — End-of-Booking cost split.

Distribution methods are configurable per unit, property, or building to match your management style. Once calculated:

• Charges can be added to tenant invoices as part of their regular payment schedule.
• Alternatively, charges can be deducted from the security deposit at check-out.
• Tenants are notified automatically with a full, transparent cost breakdown showing how their share was calculated.

How Tenant Overage Charges Are Created

Pair with other Utilities sections

Overage flow pairs with Finance — Contract Values tab and Tenant Portal — Utilities — segment clusters with Finance — Tenant category filter. Full pairing matrix: Utilities section cross-reference.

When a bill is entered and exceeds the Bills Included ceiling, Vivin automatically generates an overage charge for the affected tenants. Here is the full flow:

1. Bill entered for Property A, Electricity, March, €80
2. Ceiling checked — Property A has Bills Included of €50 for electricity
3. Overage calculated — €80 − €50 = €30 overage
4. Tenants identified — all active bookings in Property A during March are identified
5. Allocation row created — pending rows appear on Utilities → Allocations for operator review (when Account Settings → Utilities has Tenant Notification set to Charge or Notify & Charge)
6. Approved and charged — Vivin internal users approve the allocation. Both Charge and Notify & Charge add a line to the tenant payment plan on approval; Notify & Charge also notifies the tenant about the overage
7. Tenant notified — when your communication rules cover utility charges, the tenant may receive email or portal messaging about the new amount

If multiple units exist within a property and each has a different Bills Included ceiling (configured at the unit level), the overage is calculated independently for each unit.

Key Business Rules for Utilities

Summary

1. Bills Included is a per-property ceiling. Set it during property creation (Step 3) or edit it afterward in the property's payment settings. It represents the maximum utility cost absorbed into the rent — anything above this becomes a tenant charge.

2. Missing bill data = missing overage charges. If you forget to enter a utility bill for a month, no overage will be calculated for that period. Use the "Days Missing Data" chart in the Overview tab to identify and fill gaps.

3. Billing periods must be accurate. A bill must be assigned to the period it covers, not the period it was received. Entering a January bill in February is fine — just ensure the billing period is set to January.

4. Account IDs must be unique per utility per property. Each utility connection requires a unique account ID. If two properties share the same electricity meter (unusual but possible), they will share the same connection entry.

5. Overages are calculated at the property level by default. If your property has multiple units, the overage is split across all active bookings. Configure Bills Included at the unit level if different units should have different ceilings.

Utilities guide subsection index

Pair with other Utilities module guide sections

This index pairs Utilities tab sections with Related subsections — use it when overage lines on Bookings — Payment Plan disagree with Allocations or Finance ledgers. Full pairing matrix: Utilities section cross-reference.

Subsection	When to open it	Pair with
Portfolio scoping (Select properties)	Multi-building scope before tab work	Glossary — Server-driven search picker, Finance — Property and listing filters
Tab load failures	Red alert when a tab fetch fails	Glossary — Directory list load failures, FAQ — list page load failures
How Utility Billing Works	Bills Included ceiling model	Listings — Step 3 Extra payments, Settings > Utilities
Overview tab	Portfolio KPIs and missing-bill gaps	Entering Monthly Utility Bills, Finance — Tenant category filter
Connections tab	Supplier account IDs per property	Listings — Creating a New Property, Onboarding a New Property
Bills tab	AI invoice reader and bill entry	Automation & AI — AI invoice reader, Entering Monthly Utility Bills — Step 2, AI usage API (utility_bill_extraction)
Timeline tab	Chronological bill history	Bills tab, Entering Monthly Utility Bills
Cost map tab	Property × month cost heatmap	Sales — Multicalendar, Listings — Bills Included
Allocations tab	Tenant overage charge review	Bookings — Payment Plan tab, Notifications — Payment overdue alerts
How Tenant Overage Charges Are Created	Ceiling split and payment-plan posting	Finance — Contract Values tab, Tenant Portal — Utilities
Key Business Rules for Utilities	Overage invariants and notification hooks	Notification triage, Settings > Tenant categories
Deeper workflow reads	Step-by-step procedures in this module	Common Workflows hub subsection index, Entering Monthly Utility Bills
Lockout catch-up after password recovery	Sign-in restored; module backlog accumulated	Common Workflows — Lockout catch-up, Getting Started — Lockout catch-up, Resetting a Management User Password — Step 3
Pending manual receipt approval	Recorded bank transfers still pending until Approve payments	Common Workflows — Pending manual receipt approval, Finance — Pending manual payments, FAQ — Manual receipt still pending
Reject/revert mistaken receipts	Duplicate or wrong-booking receipts after Approve	Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, Glossary — Credit note (payment reject/revert)
Notification row-click navigation	/notifications row-click before overage triage on Allocations	Common Workflows — Notification row-click navigation, Notification triage — Step 4, Allocations tab
Payment alert to receivables triage	payment overdue on approved utility overage lines	Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1, Notifications — Payment overdue alerts
Confirmation alert triage	Upcoming alerts before first bill cycle on new properties	Common Workflows — Confirmation alert triage, Onboarding a New Property — Step 6, Entering Monthly Utility Bills
Portfolio segmentation by tenant category	Review one tenant segment across modules	Common Workflows — Portfolio segmentation, Settings > Tenant categories, Finance — Tenant category filter, Tenants — Tenant category filter
Finance debt receivables triage	Utility overage In Debt on Allocations may not appear in rent-only Top debtors	Common Workflows — Finance debt receivables triage, Finance — Finance debt receivables triage, FAQ — Finance debt receivables triage hub, Allocations tab, Entering Monthly Utility Bills (finance-overview-debt-aging-expanded-bucket.png, finance-overview-debt-aging-walkthrough-flow.mp4)
Finance Income status drill-down	Utility overage In Debt lines may appear in Income → In debt month modal	Common Workflows — Finance Income status drill-down, Finance — Income status drill-down, FAQ — Finance Income status drill-down hub, Entering Monthly Utility Bills — Finance Income status drill-down, Bills tab (finance-overview-income-status-in-debt-modal.png, finance-overview-income-drill-down-flow.mp4)
Cash flow forecast drill-down	Utility overage collections appear on Cash flow forecast All payments	Common Workflows — Cash flow forecast drill-down, Finance Income status drill-down, Finance — Income chart and cash flow forecast, FAQ — Cash flow forecast drill-down hub, Entering Monthly Utility Bills — Cash flow forecast drill-down, Bills tab (finance-overview-cash-flow-all-payments-modal.png, finance-overview-cash-flow-day-view.png, finance-overview-cash-flow-drill-down-flow.mp4)
Utilities section cross-reference	Per-tab pairing matrix	Module cross-reference, Finance guide subsection index

Utilities section cross-reference

Use this table when one Utilities tab or section naturally leads into another module, workflow, or concept — each row links to the docs you should read before or after acting in that section.

Utilities tab / section	Pair with these docs
Portfolio scoping (Select properties)	Glossary — Server-driven search picker, Finance — Property and listing filters
Tab load failures	Glossary — Directory list load failures
How Utility Billing Works	Listings — Step 3 Extra payments, Settings > Utilities
Overview tab	Dashboard module, Entering Monthly Utility Bills, Portfolio KPI review, Portfolio KPI review — Step 6, Finance — Tenant category filter, Glossary — Tenant category
Connections tab	Listings — Creating a New Property, Onboarding a New Property
Bills tab	Automation & AI — AI invoice reader, Create New menu — Upload Utility Bills, Landlord MCP — Extended account tools (create-bill, list-bills, get-bill; prefer UI Upload PDF for AI extraction), Entering Monthly Utility Bills — Step 2, AI usage API (utility_bill_extraction on GET /ai-usage/summary)
Timeline tab	Bills tab, Entering Monthly Utility Bills
Cost map tab	Sales — Multicalendar, Listings — Bills Included
Allocations tab	Bookings — Payment Plan tab, Settings > Utilities — Tenant Notification, Notifications — Payment overdue alerts, Finance — Tenant category filter, Bookings — Other filters tenant category, Tenant MCP — Property, payments, and portal tools (get-payment-info), Entering Monthly Utility Bills — Step 4
How Tenant Overage Charges Are Created	Bookings — Payment Plan tab, Finance — Contract Values tab, Handling a Late Payment — Step 1, Notifications — Payment overdue alerts, Finance — Tenant category filter, Bookings — Other filters tenant category, Tenants — Tenant category filter, Glossary — Tenant category, Landlord MCP — Bookings, properties, and listings (get-booking), Tenant MCP — Property, payments, and portal tools (get-payment-info; parity with Tenant Portal — Utilities)
Key Business Rules for Utilities	Tenant Portal, Notification triage, Notifications — Payment overdue alerts, Settings > Tenant categories, Glossary — Tenant category

---

Related

Pair with other Utilities module guide sections

Related below links this module to settings, concepts, workflows, and escalation paths. Pair Documentation map & escalation with Modules hub — Documentation map & escalation; pair Upstream & downstream workflows with Common Workflows — Workflow cross-reference. Topic-to-section pairing in sections above: Utilities guide subsection index · Utilities section cross-reference. Full hub matrix: Module cross-reference · Modules hub subsection index.

Documentation map & escalation

Pair with other Utilities module guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Hub parity: Modules hub — Documentation map & escalation. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Modules hub — Hub pairing matrix across operator workspaces
• Management Frontend Deep Links — Bookmark /utilities tabs (Overview, Bills, Cost map)
• Glossary — Term definitions used across utility billing and overage workflows
• Utilities section cross-reference — Tab-to-module pairing table on this page

Upstream & downstream workflows

Pair with other Utilities module guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Entering Monthly Utility Bills (section cross-reference; Deeper workflow reads; hub) — Step-by-step monthly billing workflow paired with this module
• Portfolio KPI review (section cross-reference; Deeper workflow reads; hub) — Reconcile Days Missing Data and Missing bill gaps during month-end review
• Handling a Late Payment — Step 1 (section cross-reference; Deeper workflow reads; hub) — Triage unpaid overage lines on tenant payment plans after payment overdue row-click
• Notifications — Payment overdue alerts — Operator Payments category rows when approved utility overage lines pass due date without pay-in
• Notification triage (section cross-reference; Deeper workflow reads; hub) — Clear utility-charge or payment alerts after posting bills
• Managing a Check-out & Deposit Refund (section cross-reference; Deeper workflow reads; hub) — Final utility overages to settle before deposit release (Step 5)
• Onboarding a New Property (section cross-reference; Deeper workflow reads; hub) — Wire utility IDs during property wizard Step 6 before first bill upload

Deeper workflow reads

Pair with other Utilities module guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide reciprocates with [Deeper workflow reads](../modules/utilities/index.md#deeper-workflow-reads) anchors on Module documentation hubs bullets — hub parity: Modules hub — Deeper workflow reads. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Entering Monthly Utility Bills — Step-by-step monthly billing workflow paired with this module (section cross-reference; Deeper API reads; hub)
• Portfolio KPI review — Reconcile Days Missing Data and Missing bill gaps during month-end review (section cross-reference; Deeper API reads; hub)
• Handling a Late Payment — Step 1 — Triage unpaid overage lines on tenant payment plans after payment overdue row-click (section cross-reference; Deeper API reads; hub)
• Notification triage — Clear utility-charge or payment alerts after posting bills (section cross-reference; Deeper API reads; hub)
• Managing a Check-out & Deposit Refund — Final utility overages to settle before deposit release (Step 5) (section cross-reference; Deeper API reads; hub)
• Onboarding a New Property — Wire utility IDs during property wizard Step 6 before first bill upload (section cross-reference; Deeper API reads; hub)

Settings that shape Utilities

Pair with other Utilities module guide sections

Settings bullets pair with Account Settings — Tab cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Settings > Utilities — Chargeable utility types, Tenant Notification (None / Charge / Notify & Charge), and Charge Time (Every Month / End of Booking)
• Settings > Categories — Charge-type tags on utility overage line items in the payment plan
• Settings > Tenant categories — Segment definitions when utility overage collections cluster on one cohort — pair with Finance — Tenant category filter and Entering Monthly Utility Bills — Step 4
• Settings > Preferences — In-app notifications — Account-wide utility or payment alerts after overage lines post
• Settings > Emails — Utility overage reminder Communication Rules after bills post to Payment plan

Deeper concept reads

Pair with other Utilities module guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Automation & AI — AI invoice reader and property-matching pipeline behind Upload bills (section cross-reference; hub)
• Landlord MCP — Account-scoped create-bill, list-bills, get-bill, and get-booking for bill entry, ledger review, and overage spot-checks — see Entering Monthly Utility Bills; prefer UI Upload PDF for AI extraction (section cross-reference; hub)
• Tenant MCP — Booking-scoped get-payment-info and notify-landlord when external assistants surface utility overage context — parity with Tenant Portal — Utilities (section cross-reference; hub)
• Create New menu — Upload Utility Bills — Batch PDF upload without opening Utilities first (section cross-reference; hub)
• Tenant Portal — Where tenants view utility consumption and charges when portal utilities access is enabled (section cross-reference; hub)
• FAQ — Tenant contract signing blocked — No PDF yet, mandatory Your Details gates, category locks, or Lease purpose; portal signing vs paper upload on Contract Info
• Payment Allocation — Correcting mistaken receipts — Reject and revert on Finance → Transactions (section cross-reference; hub)
• Integrations & Distribution — Utility billing is independent of marketplace distribution; configure types under Payments settings first (section cross-reference; hub)
• Booking Lifecycle — Computed Upcoming → Ongoing → Ended / Canceled status model, list filters, and Timeline (section cross-reference; hub)

Operator modules (pairing surfaces)

Pair with other Utilities module guide sections

Module hub bullets pair with Modules — Module cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Audit — Discounts tab — Portfolio-wide discounted contract values when reconciling utility overage goodwill or rent relief
• Finance > Contract values — Portfolio export when reconciling utility overages across bookings
• Finance — Tenant category filter — In Debt triage by tenant segment when overages cluster (Step 4 of Entering Monthly Utility Bills)
• Bookings — Other filters tenant category — Mirror segment filter when Finance cache parity lags
• Tenants — Tenant category filter — Profile-count cross-check before changing utility notification rules account-wide
• Analytics — Maintenance tab — Utility spend spikes alongside Operations linked cash flows
• Dashboard module — Occupancy and Days Missing Data KPIs that pair with Utilities Missing tabs
• Sales — Overview tab — Occupancy heatmap when utility overages correlate with vacancy signals
• Listings > Creating a New Property — Configure utility IDs and Bills Included ceilings
• Listings — Step 3 Extra payments — Bills Included ceiling source for overage calculations documented on this page
• Bookings > Payment Plan Tab — Where tenant overage charges appear
• Bookings — Contract Info — Per-booking Bills Included ceiling overrides the property default

Lockout catch-up after password recovery

Pair with other Utilities module guide sections

Operational backlog after sign-in recovery pairs with Resetting a Management User Password — Step 3. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Lockout catch-up after password recovery — Hub matrix when sign-in was restored mid month-end before supplier bills were entered
• Getting Started — Lockout catch-up after password recovery — Canonical operational backlog mesh
• Entering Monthly Utility Bills — Catch up on Bills tab ingestion delayed by lockout
• Overview tab — Days Missing Data gaps that widened during lockout
• Pending manual receipt approval — Overage receipt approval mesh after lockout-delayed bill entry

Pending manual receipt approval

Pair with other Utilities module guide sections

Receipt approval pairs with Finance — Pending manual payments and Bookings — Transactions tab. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Pending manual receipt approval — Hub matrix when overage lines on Payment Plan still show pending until Approve payments confirms tenant transfers

• Entering Monthly Utility Bills — Step 4b — Approve overage receipts after supplier bill ingestion

• Finance — Pending manual payments — Amber Pending chip on Finance → Transactions

• Bookings — Payment Plan tab — Overage charges awaiting receipt approval

• FAQ — Manual receipt still pending — Why allocation totals may lag until approval

• FAQ — Pending manual receipt approval hub — Symptom table for Approve payments / amber Pending

Reject/revert mistaken receipts

Pair with other Utilities module guide sections

Receipt cleanup pairs with Finance — Row actions on in-payment rows and Bookings — Row actions on in-payment rows. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Reject/revert mistaken receipts — Hub matrix when duplicate overage receipts need Reject / Revert after Approve

• Entering Monthly Utility Bills — Overage workflow when tenant payments were recorded twice

• Finance — Row actions on in-payment rows — Portfolio reject/revert on overage receipt lines

• Payment Allocation — Correcting mistaken receipts — Two-layer model and credit note follow-up

• Allocations tab — Reconcile tenant charges after receipt cleanup

• FAQ — Reject/revert mistaken receipts hub — Symptom table for Reject / Revert / Issue credit notes

Check-out ledger cleanup before refund

Pair with other Utilities module guide sections

Duplicate-transfer cleanup pairs with Reject/revert mistaken receipts and Managing a Check-out. Hub parity: Common Workflows — Check-out ledger cleanup before refund. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Check-out ledger cleanup before refund — Hub matrix when duplicate overage transfer is mistaken for unpaid utility before deposit release

• Reject/revert mistaken receipts — Reject / Revert duplicate before Ready To Refund

• Managing a Check-out — Step 6 — Canonical departure-week duplicate cleanup before refund

• Common Workflows — Check-out collections before refund — Real arrears contrast (tenant did not pay)

• Entering Monthly Utility Bills — Step 4 — Unpaid overage vs duplicate transfer on Transactions

• Managing a Check-out — Step 6 — Final utility mesh after ledger cleanup

• FAQ — Check-out ledger cleanup before refund hub — Symptom table for phantom In Debt / Ready To Refund blocked when tenant paid once

Utility overage collections

Pair with other Utilities module guide sections

Utility overage arrears pair with Entering Monthly Utility Bills — post bills first, then collections. Hub parity: Common Workflows — Utility overage collections. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Utility overage collections — Hub matrix: bill posting → collections (utilities-allocations-row-breakdown-expanded.png, finance-contract-values-in-debt-filter.png, utilities-allocations-review-flow.mp4)

• Entering Monthly Utility Bills — Steps 2–4 — Canonical posting before collections

• Entering Monthly Utility Bills — Step 4b — Pending overage receipt mesh

• Handling a Late Payment — Step 1 — Collections after overage posts

• Allocations tab — Overage math review before Payment Plan lines post

• Bills tab — Supplier bill entry upstream of overage charges

• Common Workflows — Cancellation collections before void — Utility overage on Canceled stay — not rent pre-cancel mesh

• FAQ — Utility overage collections hub — Symptom table for unpaid utility overage on Payment Plan after bill posting

Cancellation collections before void

Pair with other Utilities module guide sections

Utility overage on Canceled stays pair with Entering Monthly Utility Bills — not rent pre-cancel mesh. Hub parity: Common Workflows — Cancellation collections before void. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Cancellation collections before void — Hub matrix when utility overage on Canceled stay is mistaken for rent pre-cancel collections

• Entering Monthly Utility Bills — Step 4 — Post-cancel utility overage — not Step 2 rent mesh

• Cancelling a Booking — Step 2 — Rent/fee arrears before void only

• Handling a Late Payment — Step 1 — Collections on utility overage lines

• Common Workflows — Check-out collections before refund — Departure-week utility contrast

• FAQ — Cancellation collections before void hub — Symptom table for In Debt blocking Cancel booking until Payment Plan settles

Check-out collections before refund

Pair with other Utilities module guide sections

Rent arrears mistaken for utility overage pair with Managing a Check-out — not Entering Monthly Utility Bills overage mesh. Hub parity: Common Workflows — Check-out collections before refund. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Check-out collections before refund — Hub matrix when rent/fee In Debt blocks Ready To Refund (not utility overage mesh)

• Entering Monthly Utility Bills — Step 4 — Utility overage contrast — Check-out final utilities handoff

• Managing a Check-out — Step 6 — Rent/fee settlement before refund

• Handling a Late Payment — Step 1 — Collections on rent lines

• Allocations tab — Confirm line is rent/fee, not overage, before bill re-post

• Common Workflows — Check-out ledger cleanup before refund — Duplicate overage transfer contrast

• Common Workflows — Utility overage collections — Unpaid utility overage lines — distinct mesh

• FAQ — Check-out collections before refund hub — Symptom table for rent/fee In Debt blocking Ready To Refund before deposit release

Handling a Late Payment collections

Pair with other Utilities module guide sections

Utility overage In Debt lines pair with Entering Monthly Utility Bills — use Handling a Late Payment for collections, not rent Top debtors alone. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Handling a Late Payment collections hub — Hub matrix when utility overage triage needs collections Steps 1–6 (utilities-allocations-row-breakdown-expanded.png, finance-contract-values-in-debt-filter.png, bookings-detail-transactions-approve-payment-modal.png)
• Allocations tab — Overage lines posted to Payment Plan
• Entering Monthly Utility Bills — Step 4 — Canonical overage posting before collections
• Handling a Late Payment — Step 1 — Collections on utility In Debt
• Common Workflows — Utility overage collections — Utility-specific collections mesh
• Finance — Contract Values tab — In Debt filter for utility lines
• Common Workflows — Check-out collections before refund — Rent line mistaken for utility overage
• FAQ — Handling a Late Payment collections hub — Symptom table for triage surface → collections step pairing

Check-out vs cancellation

Pair with other Utilities module guide sections

Utility overage on Canceled stays posts via Entering Monthly Utility Bills — not Managing a Check-out — Step 6 final utilities mesh on completed stays. Hub parity: Common Workflows — Check-out vs cancellation. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Check-out vs cancellation — Hub matrix: utility overage routing by lifecycle exit (utilities-allocations-row-breakdown-expanded.png, bookings-list-canceled-tab.png)
• Entering Monthly Utility Bills — Step 4 — Overage on Canceled stays
• Common Workflows — Check-out final utilities handoff — Final meter reads on Ended path
• Allocations tab — Overage lines after bill posting on either path
• Managing a Check-out — Step 6 — Completed stay utility settlement
• Cancelling a Booking — Step 2 — Pre-cancel rent/fee settlement (not utility mesh)
• FAQ — Check-out vs cancellation — Symptom table for lifecycle exit routing

Deposit missing on Finance Deposits

Pair with other Utilities module guide sections

Departure-week utility close can coincide with deposit release on Finance → Deposits — clear or widen the toolbar date range when the booking Deposit tab shows data but the portfolio row is hidden. Hub parity: Common Workflows — Deposit missing on Finance Deposits. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Deposit missing on Finance Deposits — Hub matrix (finance-deposits-date-range-toolbar-default.png, finance-deposits-date-range-clear-flow.mp4)
• Entering Monthly Utility Bills — Deposit missing on Finance Deposits — Widen range before departure deposit release (Step 5)
• Allocations tab — Overage lines before deposit refund mesh
• Finance — Deposits tab — Portfolio refund queue after utility month-end
• Managing a Check-out — Deposit missing on Finance Deposits — Step 5 refund triage after clearing range
• Partly collected security deposit — Partial paid card empty until range clears
• FAQ — Deposit missing on Finance Deposits — Symptom table for toolbar date range triage

Notification row-click navigation

Pair with other Utilities module guide sections

Approved utility overage lines that pass due date without pay-in surface payment overdue rows — /notifications row-click usually lands on Bookings first; cross-check Allocations tab and Entering Monthly Utility Bills — Step 4 before you re-post supplier bills. Hub parity: Common Workflows — Notification row-click navigation. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Notification row-click navigation — Hub matrix (notifications-row-navigate-to-booking-detail.png, notifications-row-navigation-flow.mp4)
• Notifications module — Notification row-click navigation — Canonical /notifications row-click pairing
• Dashboard — Notification row-click navigation — Bell General vs full /notifications row-click
• Bookings — Notification row-click navigation — Booking sidebar when alert carries bookingId (most overage alerts)
• Tenants — Notification row-click navigation — Tenant profile when alert carries tenantId
• Listings — Notification row-click navigation — Property or unit sidebar when alert carries listingId or propertyId
• Operations — Notification row-click navigation — Turnover-week alerts that row-click into Bookings first
• Sales — Notification row-click navigation — Channel-import alerts before Multicalendar review
• Analytics — Notification row-click navigation — Month-range KPI charts after row-click opens booking context
• AI Chat — Notification row-click navigation — Verify assistant-cited alerts by row-click before operational follow-up
• Audit — Notification row-click navigation — Discounts / Manual Blocks month-end review after row-click
• Legacy /properties URLs — Notification row-click navigation — Legacy bookmarks that land in Listings during alert triage
• Booking engine details — Notification row-click navigation — Engine-sourced alerts before Full integration payload edits
• Inbox — Notification row-click navigation — Bell Inbox link deep-link vs General row-click
• Allocations tab — Overage charge review after row-click opens booking context
• Bills tab — Supplier bill entry when alert cites missing utility data
• Notification triage — Step 4 — Row-click before Step 5
• Payment alert to receivables triage — Ongoing/Ended payment overdue row-click on overage lines
• Confirmation alert triage — Upcoming Booking created / Payment received row-click
• Entering Monthly Utility Bills — Notification row-click navigation — Overage alerts during Step 4 verify
• FAQ — Notification row-click navigation — Target field order (link, bookingId, tenantId, listingId, propertyId)

Payment alert to receivables triage

Pair with other Utilities module guide sections

When approved overage lines on Bookings — Payment Plan pass due date without pay-in, payment overdue alerts row-click into Bookings — finish Handling a Late Payment — Step 1 and reconcile Allocations tab before you trust Overview Missing KPIs. Hub parity: Common Workflows — Payment alert to receivables triage. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Payment alert to receivables triage — Hub matrix (notifications-row-navigate-to-booking-detail.png, notifications-row-navigation-flow.mp4, finance-overview-debt-aging-walkthrough-flow.mp4)
• Notifications module — Payment alert to receivables triage — Payments category row-click entry
• Dashboard — Payment alert to receivables triage — Total Debt KPI after alert row-click
• Bookings — Payment alert to receivables triage — Payment Plan / Transactions on opened booking
• Finance — Payment alert to receivables triage — Overview → Debt Aging after single-booking triage
• Tenants — Payment alert to receivables triage — With Debt cross-check on tenant profile
• Listings — Payment alert to receivables triage — Bills Included ceiling context on property bookings
• Operations — Payment alert to receivables triage — Unpaid move-in lines before key handover
• Sales — Payment alert to receivables triage — Channel-import schedules behind overdue alerts
• Analytics — Payment alert to receivables triage — Revenue trend may lag until receivables clear
• AI Chat — Payment alert to receivables triage — Validate assistant debt answers after receivables triage
• Audit — Payment alert to receivables triage — Discounts review when receivables lag behind goodwill lines
• Legacy /properties URLs — Payment alert to receivables triage — Collections on bookings tied to redirected properties
• Booking engine details — Payment alert to receivables triage — Engine-sourced schedules behind overdue alerts
• Inbox — Payment alert to receivables triage — payment overdue on General before WhatsApp chase
• Allocations tab — Overage math review when alert cites utility charges
• How Tenant Overage Charges Are Created — Ceiling split and payment-plan posting rules
• Notification row-click navigation — Row-click on /notifications before Allocations reconcile
• Pending manual receipt approval — Amber Pending before overage collections sign-off
• Confirmation alert triage — Contrast Upcoming vs Ongoing/Ended alerts
• Entering Monthly Utility Bills — Step 4 — Verify overage lines after supplier bill approval
• Handling a Late Payment — Step 1 — Canonical receivables triage on overage lines
• FAQ — Payment alert to receivables triage — Alert-type contrast table
• FAQ — Payment alert to receivables triage hub — Utility overage lines behind overdue alerts symptom table

Finance debt receivables triage

Pair with other Utilities module guide sections

Utility overage In Debt on Allocations tab may not appear in rent-only Top debtors — scope Debt Aging after bill-cycle charges post. Hub parity: Common Workflows — Finance debt receivables triage. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Finance debt receivables triage — Hub matrix (finance-overview-income-chart-debt-aging.png, finance-overview-debt-aging-walkthrough-flow.mp4)
• Payment alert to receivables triage — Single-booking alert triage before portfolio surfaces
• Finance — Finance debt receivables triage — Debt Aging Top debtors canonical surface
• Pending manual receipt approval — Clear amber Pending before Top debtors sign-off
• Dashboard — Finance debt receivables triage — Total Debt headline vs Finance drill-down
• Bookings — Finance debt receivables triage — Payment Plan on opened booking
• Handling a Late Payment — Finance debt receivables triage — Debt Aging on Step 1 before outreach
• Portfolio KPI review — Finance debt receivables triage — Month-end Top debtors on Step 7
• FAQ — Finance debt receivables triage hub — Symptom table for four-surface triage
• Allocations tab — Tenant overage lines behind utility receivables
• Overview tab — Missing KPI after approved overage lines

Finance Income status drill-down

Pair with other Utilities module guide sections

Utility overage In Debt lines may appear in Income → In debt month modal — distinguish from rent Top debtors on Debt Aging. Hub parity: Common Workflows — Finance Income status drill-down. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Finance Income status drill-down — Hub matrix (finance-overview-income-status-in-debt-modal.png, finance-overview-income-drill-down-flow.mp4)
• Finance debt receivables triage — Debt Aging Top debtors when payment-line modal is not enough
• Finance — Income status drill-down — Stacked Income chart canonical surface
• FAQ — Finance Income status drill-down hub — Symptom table for segment vs Debt Aging
• FAQ — Finance Income status drill-down — Paid / Scheduled / In debt segment-click habit
• Portfolio KPI review — Finance Income status drill-down — Month-end Income reconciliation on Step 7
• Entering Monthly Utility Bills — Finance Income status drill-down — Utility overage In Debt on Step 4
• Utilities — Finance debt receivables triage — Utility overage vs rent Top debtors

Cash flow forecast drill-down

Pair with other Utilities module guide sections

Utility overage collections appear on Cash flow forecast All payments — distinguish from rent Top debtors on Debt Aging. Hub parity: Common Workflows — Cash flow forecast drill-down. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Cash flow forecast drill-down — Hub matrix (finance-overview-cash-flow-all-payments-modal.png, finance-overview-cash-flow-day-view.png, finance-overview-cash-flow-drill-down-flow.mp4)
• Finance Income status drill-down — Paid / Scheduled / In debt segments — not collections history
• Finance — Income chart and cash flow forecast — Canonical Cash flow forecast chart surface
• FAQ — Cash flow forecast drill-down hub — Symptom table for collections vs Income / Dashboard
• FAQ — Cash flow forecast drill-down — Month / Day bar-click habit
• Portfolio KPI review — Cash flow forecast drill-down — Month-end collections reconciliation on Step 7
• Entering Monthly Utility Bills — Cash flow forecast drill-down — Utility overage collections on Step 4
• Allocations tab — Tenant overage lines behind utility collections

Confirmation alert triage

Pair with other Utilities module guide sections

Upcoming Booking created / Payment received alerts on newly wired properties row-click into Bookings — finish Onboarding a New Property — Step 6 and Entering Monthly Utility Bills before you bulk-clear /notifications during first bill cycle. Hub parity: Common Workflows — Confirmation alert triage. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Confirmation alert triage — Hub matrix (notifications-row-navigation-flow.mp4)
• Notifications module — Confirmation alert triage — Canonical inbox pairing
• Bookings — Confirmation alert triage — Transactions / Contract Info on Upcoming imports
• Dashboard — Confirmation alert triage — Post-login Upcoming alert backlog on bell
• Tenants — Confirmation alert triage — Tenant Info / Category on confirmation-week clusters
• Listings — Confirmation alert triage — Channel import bookings on go-live properties
• Operations — Confirmation alert triage — Turnover prep after confirmation receipts approved
• Sales — Confirmation alert triage — Channel-import Upcoming alerts before Channels linking
• Analytics — Confirmation alert triage — Upcoming alerts during month-end KPI review
• AI Chat — Confirmation alert triage — Assistant-cited confirmation backlog before bulk mark-read
• Audit — Confirmation alert triage — Month-end Discounts review after confirmation receipts approved
• Legacy /properties URLs — Confirmation alert triage — First alerts after legacy redirects land in Listings
• Booking engine details — Confirmation alert triage — White-label Upcoming alerts before payload sync
• Inbox — Confirmation alert triage — WhatsApp thread after Payment received row-click
• Connections tab — Supplier account IDs before first bill upload
• Bills tab — First supplier bill after property go-live
• Notification row-click navigation — Row-click on /notifications before mark-read
• Payment alert to receivables triage — Contrast Upcoming vs Ongoing/Ended payment overdue
• Pending manual receipt approval — Payment received alert until Approve payments
• Onboarding a New Property — Step 6 — Wire utility IDs before first bill cycle
• Entering Monthly Utility Bills — Confirmation alert triage — First overage cycle after go-live alerts
• Notification triage — Confirmation alert triage — Steps 4 / 5 path
• FAQ — Confirmation alert triage — Alert-type table and bulk mark-read guard
• FAQ — Confirmation alert triage hub — First bill cycle after go-live alerts symptom table

New inventory to first booking handoff

Pair with other Utilities module guide sections

First utility bill cycle on new buildings starts after the first Upcoming reservation exists — pair Onboarding — Step 6 with Processing a New Booking — Step 6 before Entering Monthly Utility Bills. Hub parity: Common Workflows — New inventory to first booking handoff. Full pairing matrix: utilities-section-cross-reference · Module cross-reference.

• Connections tab — Supplier links from Onboarding — Step 6
• Onboarding a New Property — Step 7 — Upstream inventory verify before first booking
• Bookings — New inventory to first booking handoff — First Upcoming stay triggers bill cycle
• Processing a New Booking — Step 6 — Portal gates before first cycle
• Common Workflows — New inventory to first booking handoff — Hub matrix (utilities-bills-tab-missing-toggle.png, workflows-onboarding-property-wizard.mp4)
• Property setup to first arrival handoff — Downstream first bill Missing pass
• FAQ — New inventory to first booking handoff — Symptom table for property wizard → first reservation

Property setup to first arrival handoff

Pair with other Utilities module guide sections

First utility bill cycle on new buildings may show Missing supplier data — pair Onboarding a New Property — Step 6 with Entering Monthly Utility Bills — Step 5 after the first arrival month. Hub parity: Common Workflows — Property setup to first arrival handoff. Full pairing matrix: utilities-section-cross-reference · Module cross-reference.

• Bills tab — Missing toggle on first bill cycle after go-live
• Connections tab — Supplier links from Onboarding — Step 6
• Onboarding a New Property — Step 7 — Upstream inventory verify before first cycle
• Managing a Check-in — Step 1 — Arrival week parallel to first bill entry
• Common Workflows — Property setup to first arrival handoff — Hub matrix (utilities-bills-tab-missing-toggle.png, workflows-onboarding-property-wizard.mp4)
• Entering Monthly Utility Bills — Step 5 — Missing-data pass after first cycle
• Listings — Property setup to first arrival handoff — Go-live property setup upstream
• FAQ — Property setup to first arrival handoff — Symptom table for go-live → first arrival week

Confirmation to check-in handoff

Pair with other Utilities module guide sections

First utility bill cycle after go-live may overlap confirmation-week portal gates — finish Processing a New Booking — Step 6 before arrival-week utility overage triage. Hub parity: Common Workflows — Confirmation to check-in handoff. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Entering Monthly Utility Bills — Step 5 — Missing bills on Upcoming arrivals
• Confirmation alert triage — First bill cycle after go-live alerts
• Bookings — Confirmation to check-in handoff — Contract Info portal gates on Upcoming imports
• Onboarding a New Property — Step 7 — First arrival after Step 7 go-live
• Common Workflows — Confirmation to check-in handoff — Hub matrix (bookings-detail-contract-method-of-payments.png, workflows-operations-check-in-out-planning-view.png, booking-lifecycle-status-tabs-flow.mp4)
• Processing a New Booking — Step 6 — Upstream portal sanity before handoff
• Managing a Check-in — Step 1 — Downstream arrival-week entry (~7 days out)
• Pending manual receipt approval — Step 5b confirmation receipts before handoff
• FAQ — Confirmation to check-in handoff — Symptom table for Upcoming → arrival week

Check-in to check-out handoff

Pair with other Utilities module guide sections

Missing departure-week bills on Utilities → Bills should be closed via Entering Monthly Utility Bills — Step 5 before Managing a Check-out — Step 6 — mid-stay overages are distinct from final utility mesh. Hub parity: Common Workflows — Check-in to check-out handoff. Full pairing matrix: utilities-section-cross-reference · Module cross-reference.

• Bills tab — Missing toggle on departure-week cycle
• Entering Monthly Utility Bills — Step 5 — Canonical Missing bill triage
• Bookings — Check-in to check-out handoff — Final overage lines on Payment Plan
• Managing a Check-out — Step 6 — Settlement before deposit release
• Common Workflows — Check-in to check-out handoff — Hub matrix (operations-check-in-out-check-outs-next-7-days.png, bookings-timeline-view.png)
• Common Workflows — Check-out final utilities handoff — Final overages before refund
• Managing a Check-in — Step 4 — Upstream keys handed over (mid-stay bill cycle)
• FAQ — Check-in to check-out handoff — Symptom table for Ongoing → departure week

Check-out final utilities handoff

Pair with other Utilities module guide sections

Canonical departure-week mesh: Entering Monthly Utility Bills — Steps 2–4 → Managing a Check-out — Step 6 before deposit release. Hub parity: Common Workflows — Check-out final utilities handoff. Distinct from Utility overage collections (mid-stay arrears) and Check-out collections before refund (rent/fee lines). Full pairing matrix: utilities-section-cross-reference · Module cross-reference.

• Allocations tab — Final overage math review (utilities-allocations-row-breakdown-expanded.png)
• Bills tab — Missing toggle on departure-week final supplier bills
• Entering Monthly Utility Bills — Step 4 — Canonical overage posting verification
• Entering Monthly Utility Bills — Step 4b — Pending overage receipt mesh
• Bookings — Check-out final utilities handoff — Payment Plan / Deposit tab settlement path
• Managing a Check-out — Step 6 — Downstream settlement before refund
• Common Workflows — Check-out final utilities handoff — Hub matrix (utilities-allocations-review-flow.mp4, utilities-bills-tab-missing-toggle.png, bookings-detail-payment-plan-tab-schedule.png)
• Glossary — End-of-Booking cost split — Deferred posting when Charge Time is End of Booking
• FAQ — Check-out final utilities handoff — Symptom table for final utility overage blocking refund

Same-day turnover coordination

Pair with other Utilities module guide sections

Departure-week final overages on turnover units pair with Entering Monthly Utility Bills — Step 4 before incoming Managing a Check-in — Step 4 key handover — distinct from mid-stay Utility overage collections. Hub parity: Common Workflows — Same-day turnover coordination. Full pairing matrix: utilities-section-cross-reference · Module cross-reference.

• Common Workflows — Same-day turnover coordination — Hub matrix (operations-add-ticket-modal.png, bookings-timeline-day-week-month-and-sidebar.mp4)
• Bills tab — Departure-week final supplier bills on turnover units
• Allocations tab — Final overage math before incoming arrival
• Bookings — Same-day turnover coordination — Timeline overlap on shared units
• Operations — Same-day turnover coordination — Turnover ticket due date on Check-in & Check-out
• Entering Monthly Utility Bills — Same-day turnover coordination — Departure-week final overages during Step 4
• Managing a Check-out — Step 2 — Turnover ticket before incoming arrival
• FAQ — Same-day turnovers — Four-step operator habit
• Glossary — Same-day turnover — Shared-unit vocabulary

WhatsApp per-booking messaging

Pair with other Utilities module guide sections

Utility overage bill questions pair with Bookings → Communication on Entering Monthly Utility Bills — Step 4 — cross-booking Inbox lacks bill line context. Hub parity: Glossary — WhatsApp per-booking messaging hub · Common Workflows — WhatsApp per-booking messaging. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — WhatsApp per-booking messaging — Hub matrix (bookings-detail-communication-tab-whatsapp-thread.png, inbox-module-overview.png, inbox-module-triage-flow.mp4)
• Glossary — WhatsApp per-booking messaging hub — Surface table + per-guide/module mesh reciprocal hub
• Dashboard — WhatsApp per-booking messaging — Bell Inbox sub-tab vs General on post-login scan
• Notifications — WhatsApp per-booking messaging — Canonical /notifications message alert rows
• Bookings — WhatsApp per-booking messaging — Communication tab composer with Payment Plan context
• Inbox — WhatsApp per-booking messaging — Cross-booking triage and bell Inbox sub-tab
• Tenants — WhatsApp per-booking messaging — Tenant profile after Inbox name click
• Finance — WhatsApp per-booking messaging — Collections outreach with Transactions visible
• Operations — WhatsApp per-booking messaging — Maintenance ticket threads on Communication
• Listings — WhatsApp per-booking messaging — Go-live property tenant threads after channel import
• Sales — WhatsApp per-booking messaging — Channel-import message backlog during Multicalendar review
• Analytics — WhatsApp per-booking messaging — Month-end message backlog during KPI review
• AI Chat — WhatsApp per-booking messaging — Assistant-cited threads before operational follow-up
• Audit — WhatsApp per-booking messaging — Month-end communication review after Discounts audit
• Legacy /properties URLs — WhatsApp per-booking messaging — Legacy bookmarks during message triage
• Booking engine details — WhatsApp per-booking messaging — Engine-sourced tenant threads before payload sync
• Notification row-click navigation — Overage payment overdue alerts after bill cycle
• Payment alert to receivables triage — Debt triage before utility overage outreach
• Common Workflows — Notification row-click navigation — New WhatsApp message from … on /notifications vs bell Inbox
• Notification triage — WhatsApp per-booking messaging — Message pings on bell Inbox / /notifications
• Handling a Late Payment — WhatsApp per-booking messaging — Collections outreach on Step 3
• Managing a Check-in — WhatsApp per-booking messaging — Arrival-week threads before Step 4
• Managing a Check-out — WhatsApp per-booking messaging — Departure settlement on Step 6
• Processing a New Booking — WhatsApp per-booking messaging — Confirmation follow-up on Step 6
• Cancelling a Booking — WhatsApp per-booking messaging — Void outreach before Step 4
• Entering Monthly Utility Bills — WhatsApp per-booking messaging — Overage bill questions on Step 4
• Portfolio KPI review — WhatsApp per-booking messaging — Month-end message backlog on Step 7
• Manual block hygiene — WhatsApp per-booking messaging — Blocked-date questions on Step 3
• Onboarding a New Property — WhatsApp per-booking messaging — First tenant threads on Step 7 go-live
• Using in-app support — WhatsApp per-booking messaging — Self-serve Inbox / Communication before filing
• Resetting a Management User Password — WhatsApp per-booking messaging — Lockout-delayed bell Inbox after Step 3
• FAQ — WhatsApp per-booking messaging hub — Utility overage bill questions on Communication symptom table

Bot reasoning (audit)

Pair with other Utilities module guide sections

Utility overage bot questions on Communication. Hub parity: Glossary — Bot reasoning (audit) hub · Common Workflows — Bot reasoning (audit). Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Bot reasoning (audit) — Hub matrix (bookings-detail-communication-tab-bot-reasoning-expanded.png)
• Glossary — Bot reasoning (audit) hub — Surface table + per-guide/module mesh reciprocal hub
• Bookings — Bot reasoning (audit) — Canonical Communication Reasoning control
• ChatBot settings — Read-only audit vs editable persona / IF/THEN

ChatBot settings

Pair with other Utilities module guide sections

Account Settings → ChatBot pairs with Communication thread review — utility overage bot questions on communication. Hub parity: Glossary — ChatBot settings hub · Common Workflows — ChatBot settings. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — ChatBot settings — Hub matrix (settings-chatbot-tab-overview.png, settings-chatbot-status-bot-connected.png, settings-chatbot-save-rule-flow.mp4)
• Glossary — ChatBot settings hub — Surface table + per-guide/module mesh reciprocal hub
• ChatBot settings — Persona, IF/THEN rules, Status Bot pairing
• Glossary — Bot reasoning (audit) hub — Thread audit after rule changes

Rent reduction after invoicing

Pair with other Utilities module guide sections

Month-end bill cycle on Entering Monthly Utility Bills — Step 5 may overlap bookings whose rent month is already invoiced — goodwill rent cuts need Bookings → Contract Info → Change monthly rent plus external credit notes. Hub parity: Common Workflows — Rent reduction after invoicing. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Rent reduction after invoicing — Hub matrix (bookings-detail-change-monthly-rent-modal.png, bookings-rent-reduction-invoiced-floor-flow.mp4)
• Bookings — Changing contract dates and rent — Contract Info repricing entry point
• Bookings — Contract Values tab — Per-line Edit amount under the same floor
• Finance — Invoiced floor and rent edits — Why edits start on the booking, not Finance → Transactions
• Bills tab — Bill entry vs booking Contract Info repricing
• Processing a New Booking — Rent reduction after invoicing — Confirmation month already invoiced on Step 3
• Handling a Late Payment — Rent reduction after invoicing — Collections goodwill after Step 4
• Portfolio KPI review — Rent reduction after invoicing — Month-end repricing sign-off on Step 7
• Cancelling a Booking — Rent reduction after invoicing — Settlement repricing during Step 2b
• Managing a Check-in — Rent reduction after invoicing — Pre-move-in goodwill
• Managing a Check-out — Rent reduction after invoicing — Departure-week goodwill adjustments
• Notification triage — Rent reduction after invoicing — Row-click to invoiced booking on Step 4
• Entering Monthly Utility Bills — Rent reduction after invoicing — Month-end bill cycle on Step 5
• Manual block hygiene — Rent reduction after invoicing — Hold cleanup on Step 5
• Using in-app support — Rent reduction after invoicing — Self-serve before filing tickets
• Resetting a Management User Password — Rent reduction after invoicing — Lockout-delayed repricing after Step 3
• FAQ — Rent reduction after invoicing hub — Month-end utility bill cycle overlapping invoiced rent months symptom table

Occupancy KPI to block hygiene handoff

Pair with other Utilities module guide sections

Month-end Missing utility data on otherwise vacant-looking units may reflect manual holds suppressing occupancy — pair hub Common Workflows — Occupancy KPI to block hygiene handoff with Entering Monthly Utility Bills — Step 5 before blaming supplier connections. Hub parity: Common Workflows — Occupancy KPI to block hygiene handoff. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Occupancy KPI to block hygiene handoff — Hub matrix (utilities-bills-tab-missing-toggle.png, analytics-kpi-occupancy-tab.png, audit-manual-blocks-filter-scroll.mp4)
• Bills tab — Missing toggle vs hold-suppressed vacancy
• Entering Monthly Utility Bills — Step 5 — Month-end Dashboard vs Analytics mismatch
• Analytics — Occupancy KPI to block hygiene handoff — Occupancy dip signal
• Manual block hygiene — Downstream hold cleanup
• FAQ — Occupancy KPI to block hygiene handoff hub — Symptom table for vacancy vs missing bills
• Managing a Check-in — Occupancy KPI to block hygiene handoff — Timeline overlap from stale holds on Step 1
• Managing a Check-out — Occupancy KPI to block hygiene handoff — Calendar bars persist after Step 7
• Cancelling a Booking — Occupancy KPI to block hygiene handoff — Availability not restored on Step 5
• Entering Monthly Utility Bills — Occupancy KPI to block hygiene handoff — Dashboard vs Analytics vacancy mismatch on Step 5
• Notification triage — Occupancy KPI to block hygiene handoff — Vacant Units vs Analytics on Step 1
• Resetting a Management User Password — Occupancy KPI to block hygiene handoff — Lockout-delayed KPI review after Step 3
• Using in-app support — Occupancy KPI to block hygiene handoff — Calendar edit blocked after block hygiene
• Handling a Late Payment — Occupancy KPI to block hygiene handoff — Vacant Units vs Multicalendar holds on Step 1

Partly collected security deposit

Pair with other Utilities module guide sections

Deposit shortfalls pair with Finance — Deposits status summary cards and Bookings — Deposit tab. Hub parity: Common Workflows — Partly collected security deposit. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Partly collected security deposit — Hub matrix when Paid on the deposit is above zero but below Amount
• Finance — Deposit lifecycle status cards — Partial paid card for portfolio triage (#2091)
• Finance — Deposit status filter — Other filters → Deposit status → Partial paid on Bookings and Finance (#2090)
• Operations — Tickets toolbar search — Paste the full sequential ticket ID (for example S259, T27) in toolbar Search (#2074)
• FAQ — Find a ticket by its ID — Paste the full sequential ticket ID (for example S259, T27) in Operations → Tickets toolbar Search (#2074)
• FAQ — Skip automatic check-in/out tickets for one booking — Turn off Use unit contract rents and other contract details on Add booking to reveal CI/CO ticket checkboxes (#1140)
• FAQ — Same-day turnovers — Check-out + check-in on one unit same day: Operations → Check-in & Check-out, Timeline / Multicalendar, turnover tickets
• FAQ — Manual payments after Delete Booking — Delete Booking hides manual/provider_platform rows on Finance → Transactions; vIBAN and credit card stay visible (#1897)
• FAQ — Communication or Tickets load failure — Tab-scoped Refresh (Communication) or Retry (Tickets); other booking sidebar tabs stay usable
• Glossary — Directory list load failures — First-fetch directory failures show Retry / Try again; distinct from filter-empty states and booking-sidebar tab errors
• Glossary — Vacant Unit Preference — Include manual blocks counts operator holds as free on Dashboard / Sales vacancy surfaces (#1427)
• Bookings — Deposit tab — Partially paid badge and remaining helper on a single reservation
• FAQ — Partly collected security deposit — Distinct from Partial Paid rent on Payment Plan
• Finance — Deposit lifecycle status cards — Deposit lifecycle status row (#2091)
• Glossary — Deposit lifecycle status — depositStatus pill vocabulary (Partial Paid vs rent Partial Paid)
• Finance — Deposit lifecycle status cards — Deposit lifecycle status row on Finance → Deposits; click Partial paid for collection shortfalls (#2091)
• Manual block hygiene — Partly collected security deposit — Partial paid card when debt KPIs stay high after holds cleared (Step 5)
• Resetting a Management User Password — Partly collected security deposit — Lockout-delayed deposit triage after Step 3
• Using in-app support — Partly collected security deposit — File Finance module tickets when partial filter or badge behaviour is wrong
• Entering Monthly Utility Bills — Directory list load failures — Utilities tab Retry on bill entry (Step 2)
• Handling a Late Payment — Directory list load failures — Receivables directory Retry on collections triage (Step 1)
• Managing a Check-in — Directory list load failures — Check-in & Check-out Retry on arrival-week planning (Step 1)
• Notification triage — Directory list load failures — /notifications Try again before alert row-click (Step 2)
• Resetting a Management User Password — Directory list load failures — Directory Retry after lockout catch-up (Step 3)
• Using in-app support — Directory list load failures — Support inbox Retry before filing tickets

Month-end invoicing (fixed date)

Pair with other Utilities module guide sections

Finish Missing utility data + overage Pending on Entering Monthly Utility Bills — Steps 4b–5 before month-end bulk export with fixed Invoice date. Hub parity: Common Workflows — Month-end invoicing (fixed date). Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Month-end invoicing (fixed date) — Hub matrix (settings-invoicing-invoice-date-toggle.png, finance-transactions-fixed-invoice-date-banner.png, finance-transactions-bulk-toolbar-fixed-invoice-date-banner.png)
• Invoicing — Default invoice date — Account-wide toggle + Save
• Common Workflows — Bulk Hostkit invoicing — Issue allocation after fixed date is saved
• Bills tab — Missing data cleared before bulk Issue allocation
• Entering Monthly Utility Bills — Month-end invoicing (fixed date) — Steps 4b–5 overage Pending mesh
• Processing a New Booking — Month-end invoicing (fixed date) — First-month bulk export after confirmation (Step 6b)
• Handling a Late Payment — Month-end invoicing (fixed date) — Collections batch during Step 6b
• Portfolio KPI review — Month-end invoicing (fixed date) — Step 7 sign-off mesh
• Notification triage — Month-end invoicing (fixed date) — Alert cleanup before bulk Issue allocation (Step 5)
• Entering Monthly Utility Bills — Month-end invoicing (fixed date) — Finish Missing data + overage Pending (Steps 4b–5)
• Manual block hygiene — Month-end invoicing (fixed date) — Clear stale holds before Issue allocation (Step 5)
• Using in-app support — Month-end invoicing (fixed date) — Self-serve before filing wrong-date tickets
• Resetting a Management User Password — Month-end invoicing (fixed date) — Lockout-delayed month-end export after Step 3
• FAQ — Month-end invoicing (fixed date) hub — Month-end utility close overlapping fixed Invoice date bulk export symptom table

Bulk Hostkit invoicing

Pair with other Utilities module guide sections

Finish Missing utility data + overage Pending on Entering Monthly Utility Bills — Steps 4b–5 before month-end bulk Issue allocation. Hub parity: Common Workflows — Bulk Hostkit invoicing. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Bulk Hostkit invoicing — Hub matrix (finance-transactions-bulk-selection-bar.png, settings-invoicing-hostkit-series.png)
• Common Workflows — Month-end invoicing (fixed date) — Fixed Invoice date before bulk Issue allocation
• Settings > Invoicing — Hostkit invoice series — Required FR code before Issue allocation
• Finance — Invoice automation — Bulk Issue allocation / Invoice selected toolbar
• Finance — Issuing credit notes (integrated invoicing) — Issue credit notes (N) after invoiced Reject / Revert
• Bills tab — Missing data cleared before bulk Issue allocation
• Finance — Bulk Hostkit invoicing — Transactions toolbar reference
• Processing a New Booking — Bulk Hostkit invoicing — First-month Issue allocation after confirmation (Step 6b)
• Handling a Late Payment — Bulk Hostkit invoicing — Collections month-end mesh (Step 6b)
• Portfolio KPI review — Bulk Hostkit invoicing — Step 7 month-end sign-off
• Managing a Check-in — Bulk Hostkit invoicing — Move-in Pending mesh (Step 6b)
• Managing a Check-out — Bulk Hostkit invoicing — Departure-week mesh (Step 6b)
• Onboarding a New Property — Bulk Hostkit invoicing — First month-end on new inventory
• Cancelling a Booking — Bulk Hostkit invoicing — Settlement bulk export (Step 6b)
• Notification triage — Bulk Hostkit invoicing — Alert cleanup before bulk export (Step 5)
• Entering Monthly Utility Bills — Bulk Hostkit invoicing — Finish Missing data + overage Pending (Steps 4b–5)
• Manual block hygiene — Bulk Hostkit invoicing — Clear stale holds before Issue allocation (Step 5)
• Using in-app support — Bulk Hostkit invoicing — Self-serve Hostkit pacing before filing tickets
• Resetting a Management User Password — Bulk Hostkit invoicing — Lockout-delayed month-end export after Step 3
• FAQ — Bulk Hostkit invoicing slow — Hostkit HTTP 429 pacing and refresh-before-reissue habit
• FAQ — Bulk Hostkit invoicing hub — Month-end utility close overlapping bulk Issue allocation Hostkit pacing symptom table

Directory list load failures

Pair with other Utilities module guide sections

Each Utilities tab loads independently — Failed to load … + Retry on Bills, Overview, Connections, Timeline, or Allocations is a first-fetch failure, not an empty month with zero supplier rows. Pair Tab load failures with Entering Monthly Utility Bills — Step 2 bill entry. Hub parity: Common Workflows — Directory list load failures. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Directory list load failures — Hub matrix (utilities-bills-load-failure.png, utilities-overview-load-failure.png)
• Tab load failures — Per-tab Retry pattern
• Entering Monthly Utility Bills — Directory list load failures — Bill entry on Step 2
• Entering Monthly Utility Bills — Step 5 — Days Missing Data after tabs load
• Dashboard — Days Missing Data — Portfolio-wide missing-data KPI during month-end close
• FAQ — Directory list load failures — Whole-module vs empty filter state
• FAQ — Directory list load failures hub — Per-tab Utilities Retry vs empty supplier month symptom table
• Glossary — Directory list load failures hub — Surface table + per-guide/module mesh reciprocal hub

Portfolio segmentation by tenant category

Pair with other Utilities module guide sections

Segment filters pair with Settings > Tenant categories and Portfolio KPI review — Step 6. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Common Workflows — Portfolio segmentation by tenant category — Hub matrix when overage charges cluster on one tenant segment
• Portfolio scoping (Select properties) — Scope supplier bills before segment comparison
• Bookings — Other filters — Tenant category on reservations with overage lines
• Finance — Tenant category filter — Ledger segmentation when utility allocations disagree with Finance
• Settings > Tenant categories — Per-segment Bills Included and portal rules
• Portfolio KPI review — Step 6 — Optional month-end segment pass on utility overage outliers

Key glossary terms

Pair with other Utilities module guide sections

Glossary rows pair with Glossary cluster cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Glossary — End-of-Booking cost split — Charge Time → End of Booking splits daily overage across every occupied unit; still-staying roommates stay in the denominator (#2111)

• Operations — Property-level ticket search — Property-name matches share the top relevance tier with unit hits; building-scoped rows float first under an active Property filter (#2089)

• Glossary — Change history — Operator-initiated edits on Listings setup and Bookings Changelog; create-time defaults excluded (#2093)

• FAQ — Booking Changelog scope — Operator-initiated edits only; create-time defaults excluded (#2093)

• Glossary — Archived booking ledger visibility — Delete Booking hides manual/provider_platform rows on Finance → Transactions; vIBAN and credit card stay visible (#1897)

• Bookings — Provider platform payment — Non-rejected provider platform in-payment blocks Delete Booking until Reject or assign (#2076)

• FAQ — Delete Booking on integration reservation — Clear pending provider platform in-payment with Reject or assign before soft-archive (#2076)

• Listings — Property edit sidebar pills — Setup / Full integration / Photos pills on property and unit edit sidebars; replaced the old Go to details shortcut (#2082)

• Glossary — Finance tenant category cache refresh — Recategorizing a tenant on Tenants → Tenant Info force-refreshes Finance caches so Contract Values, Overview, and Deposits filters match within seconds (#2088)

• FAQ — Finance tenant category filter parity — Finance Other filters drawer lists segments on cached bookings only; mirror Bookings / Tenants when a segment is missing

• FAQ — Assign tenant category for direct booking — Add booking has no category field; assign on Tenants → Tenant Info or + Create New → Tenant before contract mail

• Glossary — SIMAR water contract ID — SIMAR (Loures e Odivelas) water bills use Cód. Local in Connections — not Nº de Contador; leading zeros stripped (#2110)

• Glossary — Per-booking maintenance ticket opt-out — Add booking checkboxes skip automatic CI/CO tickets for one reservation only; property rule unchanged (#1140)

• FAQ — Cancel Booking vs Delete Booking — Cancel for real stays with settlement; Delete soft-archives mistaken/test rows (#1897 / #2076)

• Glossary — Archived property — Archive retires a building to Listings → Archived without deleting bookings; distinct from Delete Booking (reservation soft-archive) — Listings — Archived properties

• FAQ — Archive a property — Edit property sidebar Archive / Unarchive on Listings; building-level — not Delete Booking or Cancel booking

• FAQ — Portfolio retirement decisions — Archive property (building) vs Cancel booking vs Delete Booking (reservation soft-archive) — three-way decision table

• Credit note (payment reject/revert) — Accounting follow-up when rejecting already-invoiced overage receipts

• Tenant category — Bookings, Finance, and Tenants segmentation when utility overages cluster on one cohort

• Deposit dispute — Unrelated to utility overages but often reviewed during move-out settlement in the same month-end pass

• FAQ — Automatic check-in email — Trigger matrix, 15-day cutoff, paper upload vs portal signing, Nuki-only toggle, Send / Resend on Contract Info

• FAQ — WhatsApp and email per booking — Bookings → Communication tab when tenant chatbot is enabled; Inbox for portfolio-wide triage

• FAQ — Deposit missing on Finance Deposits — Default ~3 months date range; clear or widen before triaging older move-outs or dispute row actions

• FAQ — Pending manual in-payment on /notifications — Alert persists until Approve payments clears Finance or booking Transactions

• FAQ — Uncovered Debt KPI — Finance Total Debt minus deposit offsets; pair with Debt Aging and In debt drill-down

• FAQ — Dashboard Total Debt subtitle — Post-login Total Debt card headline vs >15 days subtitle; ongoing bookings only

• FAQ — Analytics (KPI workspace) — Portfolio KPIs vs Sales/Listings/Dashboard; load-failure Try again

• FAQ — Bulk Hostkit invoicing slow — Vivin paces Hostkit API calls and retries HTTP 429 during bulk Issue allocation / Invoice selected; refresh Transactions before re-issuing

• FAQ — Lower rent below invoiced — Change monthly rent clamps and Contract Values → Edit amount blocks net below exported invoice totals; use credit notes in accounting when you truly need a reduction

• FAQ — Reject or revert an incoming payment — Reject pending rows or Revert confirmed ones; Finance → Transactions uses Reject selected bulk-only; modals warn about credit notes when Finance already invoiced

• FAQ — Finance Income status drill-down — Overview Income chart (Paid / Scheduled / In debt); click a segment for month-scoped payment-line modal; Debt Aging for booking-level receivables

• FAQ — Permission denied toast — Red You do not have permission to perform this action. toast when RBAC blocks a save; fix in Users → Role Permissions

• FAQ — Phone shows Operations only — Mobile phone user agent locks operators with Operations access to /operations; iPads and narrow desktop browsers keep the full module list

• FAQ — Notification row-click navigation — On /notifications, row click marks unread then opens link, bookingId, tenantId, listingId, or propertyId (first match); Dashboard bell General rows stay in-panel unless link is set

• FAQ — Bookings that owe money — Top debtors and overdue buckets on Finance → Overview; Total Debt KPI is not a table

• FAQ — Fixed rent on variable unit — Variable listing + equal rent every contract month → booking stores fixed headline Monthly rent; payment plan unchanged

API & companion guides

Pair with other Utilities module guide sections

API bullets pair with API Reference hub. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• API Reference — Listings & Availability — Partial ListingDto billsIncludedMaxValue ceiling partners read; operator overages reconcile here when actual bills exceed it
• API Reference — Booking Engine API — White-label PUT /listing writes that push billsIncludedMaxValue back into Vivin

Module documentation hubs

Pair with other Utilities module guide sections

Module hub bullets pair with Modules — Module cross-reference. Full pairing matrix: Utilities section cross-reference · Module cross-reference.

• Utilities module — Hub for Bills Included ceilings, Connections, AI bill upload, and tenant overage charges (this page)
• Operations module — Maintenance tickets, cash flows, check-in/out coordination, Draft ticket queues, and linked cash flows (hub)
• Dashboard module — Post-login Today, Total debt, Vacant Units, and forecast KPI snapshot with bell notification triage (hub)
• Analytics module — Month-range portfolio KPI charts (Overview, Revenue, Occupancy, ADR, RevPAR, Maintenance) with rankings and heatmaps (hub)
• Listings module — Property wizard, Channels tab, Archived inventory, and unit management (hub)
• Properties workspace — Legacy /properties URL redirects into Listings (hub)
• Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
• Finance module — Portfolio ledgers (Overview, Income, Contract Values, Transactions, Payouts, Deposits) with payment approval and deposit settlement (hub)
• Tenants module — Tenant directory, profile sidebars, With Debt segmentation, and table expand for linked bookings (hub)
• Sales module — Portfolio availability, monthly rent editing, and channel manager connections (hub)
• Inbox module — Portfolio-wide WhatsApp workspace with Dashboard bell Inbox sub-tab deep links (hub)
• Notifications module — Full /notifications history with search, filters, and row-click navigation (hub)
• AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools for portfolio Q&A (hub)
• Audit module — Portfolio-wide Manual Blocks and Discounts contract-value review (hub)
• Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)
• API Reference hub — Partner HTTP contracts, Swagger onboarding, and partial vs full feeds (hub)