How Balances Work

HelmKeep uses a transaction-based ledger system. Every member has a balance that is the sum of all their transactions. The balance is also stored as a materialized field for quick access, and it is kept synchronized with the transaction records.

Balance changes only happen through explicit transactions — task approvals, allowance payments, and manual adjustments — ensuring a complete audit trail.

Earning from Tasks

When a task with a reward amount is approved, the reward is automatically credited to the completing member's balance. This happens atomically — the task approval and balance credit occur in a single transaction to prevent inconsistencies.

Allowances

Allowances are recurring payments made to members on a schedule. Members with the balances.allowance.manage permission can configure allowances for each member. Options include:

• Weekly: Payment every week
• Biweekly: Payment every two weeks
• Monthly: Payment once a month

Each member can have one allowance configuration. The allowance processor runs on a schedule and idempotently credits the correct amount, ensuring no duplicate payments.

Balance Adjustments

Members with the balances.adjust permission can make manual adjustments to any member's balance. Adjustments create a transaction record with a reason, maintaining the full audit trail. Use this for corrections, bonuses, or deductions.

Transaction History

The Balances page shows a complete transaction history for each member. Every entry includes the amount, type (task reward, allowance, adjustment), date, and any associated notes. Members can view their own transaction history; those with the balances.view permission can see all members' histories.