Expenses

expenses lets members file expense reports. A report has lines, each in a category, with receipts uploaded as attachments. Categories carry a spend policy, which submit checks before the report goes to the approvals block. An approved report posts on the ledger, and so does its reimbursement, so what the organization owes a member is a ledger balance.

better-supabase add expenses

import { createExpenses } from "better-supabase/blocks/expenses";
import { money } from "better-supabase/commerce";

The module requires tenant, access, approvals and ledger. With outbox it records the expense_report.* events, with audit every change is audited, and with attachments lines take receipts. Amounts are bigint minor units (ADR 0037), and how the approved total posts on the ledger is in ADR 0080.

TablesCopy Anchor Link

A member reads their own reports and lines. Members with expenses.read read every report of the organization. Writes go through the functions: expenses.submit to file reports, expenses.approve to approve them (the approvals block checks it), and expenses.manage for categories and reimbursement.

Your own columnsCopy Anchor Link

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

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

// the client
const expenses = createExpenses({
  transport,
  tenant,
  fields: v.object({ project_code: v.optional(v.string()) }),
});

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

Categories and spend policiesCopy Anchor Link

const expenses = createExpenses({ transport, tenant: organizationId });

await expenses
  .saveCategory({
    key: "travel",
    name: "Travel",
    limit: money(150_000n, "EUR"),
    receiptOver: money(2_500n, "EUR"),
  })
  .orThrow();

limit caps a report's total in the category. receiptOver requires a receipt on every line above it, and needs the attachments block. Archiving a category keeps its lines; a report with a line in an archived category can't be submitted.

File and submit a reportCopy Anchor Link

const report = await expenses
  .create({ title: "Client visit, Lisbon", currency: "EUR" })
  .orThrow();

const line = await expenses
  .addLine(report.id, {
    categoryId,
    spentOn: Temporal.PlainDate.from("2026-10-14"),
    amount: money(18_900n, "EUR"),
    description: "Flight",
    merchant: "TAP",
  })
  .orThrow();

const findings = await expenses.check(report.id).orThrow();
await expenses.submit(report.id).orThrow();

A receipt is an attachment on the line: upload it with the attachments client and the subject { type: "expense_line", id: line.id }. The line's receipts counts the uploads that finished and weren't flagged as infected.

check returns what the spend policy would refuse: a category over its limit, a line over its receipt threshold without a receipt, or a line in an archived category. submit fails with EXPENSE_POLICY_VIOLATION while there are findings, and otherwise opens an approval. Lines can't change while the report is submitted; a rejected report can be edited and submitted again.

Approval and the ledgerCopy Anchor Link

The report's status follows its approval: submitted while it's pending, approved or rejected once it's decided. Members with expenses.approve decide it through the approvals block. When the approval is final, the report posts on the ledger: each category's total on its expense account (expenses:category:<key>:<currency>) against the member's payable account (expenses:payable:<user>:<currency>).

await expenses
  .reimburse(report.id, { reference: "payout-2026-10-31" })
  .orThrow();

reimburse settles the payable account from expense cash (expenses:cash:<currency>) and needs expenses.manage. Each posting has a key per report (expense:<id>:approved, expense:<id>:reimbursed), so it can't post twice. cancel withdraws a report that isn't approved yet and cancels its pending approval.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

expense_report.created, expense_report.submitted (with the approval), expense_report.approved and expense_report.reimbursed (with the ledger transaction) and expense_report.cancelled. A rejection is the approvals block's approval.rejected event. The events page lists their payloads.