Home › Library › Expense Configuration › Utility Expense Charges

Utility Expense Charges

Track utility expenses and charges for your properties

What are utility expense charges?

Utility expense charges allow you to track costs for utility services: electricity, water, gas, heating, internet and other property-related expenses. Each expense links to an expense type and can have multiple counters attached for automatic consumption tracking.

Key Features

  • Configurable expense types
  • Counter-based consumption tracking
  • Multi-zone tariffs (day/night, peak/half-peak/night)
  • Automatic and manual charge creation
  • Service provider integration
  • Document attachments: contracts, tariff schedules, and agreements can be attached to expenses; invoices and receipts to individual charges

Workflow: Expense Types → Charges

Important: Two-Step Process

The expense management system uses a two-level structure:

  1. Expense Types (Templates) — Define recurring categories like "Electricity", "Water", "Heating". Configure calculation method, pricing, and billing period. This is done once and reused monthly.
  2. Charges (Actual Bills) — Create charges from expense types for specific periods. Enter consumption data, the system calculates amounts based on the type configuration, and bills are issued to tenants.

Example: Create expense type "Electricity" once with price 0.15 EUR/kWh. Every month, create a charge for this type with actual consumption (e.g., 250 kWh), and the system calculates 37.50 EUR.

← Back to Charges Overview

Zone Prices

Multi-zone tariff system allows setting different prices for different time periods:

Code Tariff Type Description
TOTAL single-zone Total zone (single tariff)
DAY two-zone Day zone (typically 07:00-23:00)
NIGHT two-zone / three-zone Night zone (typically 23:00-07:00)
PEAK three-zone Peak zone (maximum load time)
HALF_PEAK three-zone Half-peak zone (transitional)

Note

If expense type is configured with zone prices, counter must have corresponding zones. Not all zones are required - you can use only TOTAL or combination of zones.

How to Configure

1

Step 1: Configure Expense Type

Create expense type (Electricity, Water, Gas, etc.)

2

Step 2: Configure Zone Prices

Configure zone prices for expense type

3

Step 3: Create Counters

Create counters for property

Charge Creation

Counter-based charges are created automatically or manually:

Simple charge

The simplest option - using TOTAL zone with single price. System calculates difference between previous and current reading, multiplies by price and creates one charge.

Example

Period: January 1-31, 2026
Service: Internet
Quantity: 1 unit
Price: €45.00 per unit
Total: €45.00

Multi-zone charge

For counters with different tariff zones (day/night or peak/half-peak/night), the system creates separate charge items for each zone. This accurately reflects consumption at different tariffs.

  • Counter
  • Readings
  • Consumption
  • Price
  • Amount

Example

Counter: Main meter (two-zone)
Period: January 1-31, 2026

Item 1 - DAY zone:
Previous reading: 500.00 kWh
Current reading: 600.00 kWh
Consumption: 100.00 kWh
Price: €0.15 per kWh
Amount: €15.00

Item 2 - NIGHT zone:
Previous reading: 200.00 kWh
Current reading: 250.00 kWh
Consumption: 50.00 kWh
Price: €0.08 per kWh
Amount: €4.00

Total charge: €19.00

Counter Readings

Counter readings are the basis for automatic charge calculations:

1

Step 1: Create Counter

Create counter for property

2

Step 2: Enter Readings

Enter counter readings

3

Step 3: Automatic Charge

System automatically creates charge

No Readings

If readings not submitted, charge is not created until counter data received

Manual Charge Creation (UI)

For expenses with consumption type "As Incurred" or calculation period "MANUAL", you can create charges manually through the web interface.

Properties → [Property] → Charges → Add Charge

Navigate to the Charges page for your property. If you have expenses requiring manual charges, you will see a blue "Add Charge" button.

1

Open expense selection

Click the blue "Add Charge" button to open a modal window showing all expenses available for manual charge creation.

2

Select expense

The modal displays each expense with its type badge (As Incurred/Manual), provider information, and any notes. Click on the expense you want to charge.

3

Fill charge form

Complete the charge form with charge date, billing period dates, amount, and optional notes. The form shows expense information including provider and calculation method.

When to use manual charges

  • As Incurred expenses: where the actual amount varies and must be entered after receiving the invoice
  • Manual period expenses: when you want full control over when charges are created, without automatic generation

Automatic Generation

The system can automatically create utility charges based on counter readings:

Calculation Periods

Period Description
MANUAL Charge created manually only
MONTHLY Charge created monthly
QUARTERLY Charge created quarterly
SEMI_ANNUAL Charge created semi-annually
ANNUAL Charge created annually

Calculation Periods

Calculation period determines how often charges are created:

Example

Example

  • For January 2026
  • For Q1 2026
  • For 2026

Restrictions

Automatic generation is only available if zone prices and counters are configured for expense type

Document Management

Documents can be attached at two levels in the expenses module, each serving a different purpose:

Expense Documents

Documents attached to the expense configuration itself remain accessible across all charges. Use these for:

  • Service contracts with utility providers (electricity, gas, water)
  • Maintenance agreements with contractors (heating, HVAC, elevator)
  • Tariff schedules and pricing agreements
  • Equipment certificates and installation documentation

Example: For an "Electricity" expense, you might attach the contract with the power company, tariff schedule showing day/night rates, and the meter installation certificate.

Charge Documents

Documents attached to individual charges are specific to that billing period. Use these for:

  • Monthly invoices from service providers
  • Payment receipts and confirmations
  • Billing statements for specific periods
  • Adjustment or correction notices

Example: For a January 2026 electricity charge, attach the utility company invoice for that month and the payment receipt.

REST API

Main API endpoints for utility expenses:

Service layer note

Expense Types API

GET    /api/v1/properties/{propertyId}/expenses              # List expenses
POST   /api/v1/properties/{propertyId}/expenses              # Create expense
GET    /api/v1/properties/{propertyId}/expenses/{id}         # Expense details
PUT    /api/v1/properties/{propertyId}/expenses/{id}         # Update expense
DELETE /api/v1/properties/{propertyId}/expenses/{id}         # Delete expense
POST   /api/v1/properties/{propertyId}/expenses/{id}/toggle  # Toggle active/inactive
POST   /api/v1/properties/{propertyId}/expenses/refresh-all  # Refresh all charges
POST   /api/v1/properties/{propertyId}/expenses/{id}/refresh # Refresh single expense

Charges

GET    /api/v1/properties/{propertyId}/expenses/{expenseId}/charges             # List charges
POST   /api/v1/properties/{propertyId}/expenses/{expenseId}/charges             # Create charge
GET    /api/v1/properties/{propertyId}/expenses/{expenseId}/unlinked-readings   # Get unlinked readings
GET    /api/v1/properties/{propertyId}/charges/{id}                             # Charge details
PUT    /api/v1/properties/{propertyId}/charges/{id}                             # Update charge
DELETE /api/v1/properties/{propertyId}/charges/{id}                             # Delete charge
POST   /api/v1/properties/{propertyId}/charges/{id}/confirm                     # Confirm charge

Charge Documents API

Manage documents attached to expense charges (receipts, invoices, contracts).

GET    /api/v1/properties/{propertyId}/charges/{chargeId}/documents           # List charge documents
POST   /api/v1/properties/{propertyId}/charges/{chargeId}/documents           # Upload document to charge
GET    /api/v1/properties/{propertyId}/charges/{chargeId}/documents/{id}      # Document details
PUT    /api/v1/properties/{propertyId}/charges/{chargeId}/documents/{id}      # Update document comment
DELETE /api/v1/properties/{propertyId}/charges/{chargeId}/documents/{id}      # Remove document from charge

Upload a receipt for an expense charge

POST /api/v1/properties/1/charges/42/documents
Content-Type: multipart/form-data
Authorization: Bearer <token>

file: (binary)
document_type_id: 1
comment: "Invoice for January 2026"

Expense Type Documents API

Attach, view and manage documents (contractor contracts, tariff schedules) directly on the expense type configuration.

GET    /api/v1/properties/{propertyId}/expenses/{expenseId}/documents           # List expense documents
POST   /api/v1/properties/{propertyId}/expenses/{expenseId}/documents           # Upload document to expense
GET    /api/v1/properties/{propertyId}/expenses/{expenseId}/documents/{id}      # Document details
PUT    /api/v1/properties/{propertyId}/expenses/{expenseId}/documents/{id}      # Update document comment
DELETE /api/v1/properties/{propertyId}/expenses/{expenseId}/documents/{id}      # Remove document from expense

API Example: Upload document to expense type

POST /api/v1/properties/1/expenses/3/documents
Content-Type: multipart/form-data
Authorization: Bearer <token>

file: (binary)
document_type_id: 1
comment: "Contractor agreement for heating service"

API Example

POST /api/v1/properties/1/expenses/3/charges
Content-Type: application/json
Authorization: Bearer <token>

{
  "charge_date": "2026-01-31",
  "period_start": "2026-01-01",
  "period_end": "2026-01-31",
  "charged_to_user_id": 5,
  "items": [
    {
      "counter_id": 5,
      "zone_code": "DAY",
      "previous_value": "500.00",
      "current_value": "600.00",
      "unit_price": "0.15"
    },
    {
      "counter_id": 5,
      "zone_code": "NIGHT",
      "previous_value": "200.00",
      "current_value": "250.00",
      "unit_price": "0.08"
    }
  ]
}

Expense Types

Type Name Has Counter
Communications (Internet, TV) —
Heating
Electricity
Hot Water
Cold Water
Sewage —
Security —
Concierge —
Alarm System —
Territory Maintenance —
Gas
Garbage Collection —
Taxes —
Other Expenses —
One-time Expenses —

One-Time Charges

One-time charges are used to record unexpected or irregular expenses that do not fit into regular utility or service categories.

How It Works

  1. Navigate to the property expenses page
  2. Click the "One-Time Charge" button
  3. Fill in the amount, date, billing period, and optional notes
  4. The charge will be automatically created and marked as confirmed

Characteristics

  • Consumption Type: As incurred
  • Unit: charges
  • Special Marker: Expense type code ONE_TIME (not the assigned provider, which is not shown for this container)
  • Visibility: Hidden from regular expense lists
  • Auto-create Charges: No - charges created manually only

Routes

GET /properties/{propertyId}/one-time-charges List one-time charges POST /properties/{propertyId}/one-time-charges/new Create one-time charge

Form Fields

  • Date* — The date when the expense occurred
  • Billing Period* — Select the billing period for accounting purposes
  • Amount* — The total amount to charge (required)
  • Notes — Optional description or explanation

Key Advantages:

  • Quick creation without setting up recurring expenses
  • Perfect for unexpected or irregular expenses
  • Automatically confirmed upon creation
  • Does not interfere with regular expense tracking
  • Maintains complete expense history for property
← Back to Charges Overview