Leases

leases lets units from the assets block to parties such as contacts. Rent posts on the ledger once per period, so the balance due is a ledger balance and never a second copy. Deposits are held through ledger holds while the lease runs, and members file maintenance requests on the unit.

better-supabase add leases

import { createLeases } from "better-supabase/blocks/leases";
import { money } from "better-supabase/commerce";

The module requires tenant, access, subjects, assets and ledger. With outbox it records the lease.* and maintenance_request.* events, and with audit every change is audited. Amounts are bigint minor units (ADR 0037), and how recurring charges post on the ledger is in ADR 0080.

TablesCopy Anchor Link

Members with leases.read read every lease, charge and request of the organization; a member who filed a request reads it without it. Writes go through the functions: leases.manage for leases and payments, and leases.maintain (or leases.manage) to file a request.

Your own columnsCopy Anchor Link

extraColumns adds columns to the lease_agreements table, and the client's fields schema types them.

// better-supabase.config.ts
blocks: {
  leases: { options: { extraColumns: { cost_center: "text" } } },
},

// the client
const leases = createLeases({
  transport,
  tenant,
  fields: v.object({ cost_center: v.optional(v.string()) }),
});

create validates them before the call, and every read that returns a lease parses them under lease.fields.

Create and start a leaseCopy Anchor Link

const leases = createLeases({ transport, tenant: organizationId });

const lease = await leases
  .create({
    unitId,
    party: { type: "contacts", id: contactId },
    startsOn: Temporal.PlainDate.from("2026-11-01"),
    endsOn: Temporal.PlainDate.from("2027-10-31"),
    rent: money(120_000n, "EUR"),
    frequency: "monthly",
    deposit: money(240_000n, "EUR"),
  })
  .orThrow();

await leases.activate(lease.id).orThrow();

create makes a draft. The party is any record in config.subjects, and the deposit is in the rent's currency. activate starts the lease: it fails with LEASE_OVERLAP while another active lease of the unit overlaps the dates, posts the deposit on the lease's deposit account and holds it there. A lease without endsOn runs until it is terminated.

Rent on the ledgerCopy Anchor Link

const posted = await leases.postDueRent().orThrow();

await leases
  .recordPayment(lease.id, {
    amount: money(120_000n, "EUR"),
    reference: "bank-2026-11-03-0042",
  })
  .orThrow();

postDueRent posts every period of the organization's active leases that starts on or before through (default today). Each period posts once: the lease_charges row is unique per lease and period, and its ledger transaction carries the key leases.rent:<id>:<period start>. Run it as often as you like; a second run posts nothing new, and maxRows caps one run. The SQL function post_due_rent called with the service role and a null tenant runs for every organization, which suits a scheduled job.

Each lease has a receivable account on the ledger (leases.rent:<id>). Rent moves an amount from rent income onto it, and recordPayment moves a payment from it to rent received. balanceDue on the lease is that account's balance, so a prepayment shows as a negative balance. A payment with a reference returns the first payment when you record it again.

A period that starts before the lease's end posts in full, even when the lease ends partway through it.

Renew and terminateCopy Anchor Link

await leases
  .renew(lease.id, {
    endsOn: Temporal.PlainDate.from("2028-10-31"),
    rent: money(125_000n, "EUR"),
  })
  .orThrow();

await leases
  .terminate(lease.id, {
    on: Temporal.PlainDate.from("2027-04-30"),
    reason: "Moved out",
    depositDeduction: money(15_000n, "EUR"),
  })
  .orThrow();

renew moves the end of an active lease with a fixed end to a later day. A new rent applies to the periods posted from then on. terminate ends the lease on on (default today): its status is ended on or after its end and terminated before. No rent posts for periods from that day. The deposit hold is captured for depositDeduction into rent income, and the rest goes back to the party. A draft is terminated without touching the ledger.

Maintenance requestsCopy Anchor Link

await leases
  .fileMaintenance({
    unitId,
    leaseId: lease.id,
    title: "Leaking tap in the kitchen",
    priority: "high",
  })
  .orThrow();

A request moves through open, in_progress, resolved and cancelled. updateMaintenance changes the status, the priority or the assignee and needs leases.manage; resolving a request sets resolvedAt.

SectionCopy Anchor Link

The leases section lists a party's leases on its record page, with the rent due and the deposit held.

Merging partiesCopy Anchor Link

When two records merge, the dropped record's leases move to the kept record.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

lease.created, lease.activated, lease.renewed, lease.terminated, lease.charged (one rent period), lease.paid, maintenance_request.filed and maintenance_request.updated. The events page lists their payloads.