Finance, budgets and expenses

Every read route also accepts head_office:churches:view and system:churches:view with an X-Church header. Balances move only inside the same database transaction as the ledger line that explains them, so a money account's balance always equals the sum of its ledger.

Money accounts

The church's money accounts: bank accounts, cash and any other place it keeps money. They are created and configured as bank accounts under Giving, and each paybill settles into one of them. Collections credit them; expenses, transfers, withdrawals and paid requisitions debit them.

Viewing accounts is also allowed to anyone who can transfer, withdraw, record expenses, pay requisitions or build budgets, since each of those needs to pick an account.

Transfers and withdrawals

A transfer moves money between two of the church's accounts at once. A withdrawal takes money out (to the bank, to petty cash) and waits for approval; the ledger moves only when it is approved. Someone other than the requester must approve it, unless the requester is the church admin.

# Paste your token once (it starts with mc_):
export MYCHURCH_TOKEN="mc_your_token_here"

curl -X POST https://uat-api.mychurch.co.ke/v1/transfers \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_uuid": "1f0e7d6c-0000-4000-8000-00000000f001",
    "to_account_uuid": "1f0e7d6c-0000-4000-8000-00000000f002",
    "amount": 50000,
    "description": "Paybill to building fund bank account"
  }'

{
  "success": false,
  "error": "Main paybill account holds 12000.00, not enough for this withdrawal and its cost"
}

Expenses

# Paste your token once (it starts with mc_):
export MYCHURCH_TOKEN="mc_your_token_here"

curl -X POST https://uat-api.mychurch.co.ke/v1/expenses \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sound system repair",
    "amount": 18500,
    "transaction_date": "2026-10-28",
    "reference": "INV-2210",
    "payment_mode": "mpesa",
    "account_uuid": "1f0e7d6c-0000-4000-8000-00000000f001",
    "vote_head_uuid": "2a7c5e90-0000-4000-8000-00000000e001"
  }'

payment_mode is cash, mpesa, bank, cheque or other; the date cannot be in the future. Receipts are PDF, PNG or JPEG under 10 MB.

Vote heads, years and currencies

Financial years, currencies and exchange rates can be read by anyone with church:finance:view, church:vote_heads:view, church:accounts:view or a budgets permission.

Budgets (premium)

A budget plans income and spending per vote head for a financial year; it is drafted, approved and, if needed, reopened.

Requisitions (premium)

A requisition asks for money against the budget: it is drafted with items, submitted, approved or rejected, then paid from a money account.

Reports over all of this (income statement, expenses by vote head, money account statements) are in Reports.