Documentation | API Reference

Overview

The Agreement Penalties module allows property owners to track and document financial penalties imposed on tenants for violations of rental contract terms.

Penalty Tracking

Record financial penalties with date, amount, currency, and detailed description.

Contract Block References

Link penalties to specific contract blocks (terms) that were violated.

Document Attachments

Attach photos and documents as evidence for the penalty.

Payment linking

Penalties can be linked to specific overdue payments for tracking

Multi-Currency Support

Record penalties in different currencies with automatic symbol display.

Workflow

The typical workflow for documenting penalties:

1

Document Penalty

Owner records the penalty with date, amount, currency and description.

2

Select Contract Blocks

Link the penalty to specific contract terms that were violated.

3

Attach Evidence

Upload photos and documents as supporting evidence.

4

Track History

Build a penalty history for the tenant/contract for future reference.

Permissions

Access rights for contract penalties:

Action	Who Can
Create	Property owners and their agents
View	Owners, tenants, and their agents (can view penalties against them)
Edit	Property owners and their agents
Delete	Property owners and their agents
Attach Documents	Property owners and their agents

REST API

Access contract penalties via REST API (requires JWT authentication):

Service layer note

GET    /api/v1/properties/{id}/penalties           - List penalties
POST   /api/v1/properties/{id}/penalties           - Create penalty
GET    /api/v1/properties/{id}/penalties/{pid}     - Get details
PUT    /api/v1/properties/{id}/penalties/{pid}     - Update penalty
DELETE /api/v1/properties/{id}/penalties/{pid}     - Delete penalty
POST   /api/v1/properties/{id}/penalties/{pid}/documents      - Attach document
DELETE /api/v1/properties/{id}/penalties/{pid}/documents/{did} - Detach document

Example Response

{
  "data": [
    {
      "id": 1,
      "property_id": 5,
      "contract_id": 12,
      "penalty_date": "2026-01-10",
      "amount": 500.00,
      "paid_amount": 250.00,
      "remaining_amount": 250.00,
      "is_paid": false,
      "currency": {
        "id": 3,
        "code": "UAH",
        "symbol": "₴"
      },
      "description": "Late rent payment penalty for December 2025",
      "violator": {
        "id": 15,
        "name": "John Tenant"
      },
      "documents_count": 2,
      "blocks_count": 1,
      "created_at": "2026-01-10T14:30:00+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Swagger / OpenAPI

Full API documentation with interactive testing is available in Swagger UI: /api/v1/doc

Contract Penalties