# Expense Settings UI (`/settings/expenses`)

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 61  
**Tier:** All tiers  
**Depends on:** `expenses-module`, `settings-module`, `foundation-auth-rbac`  
**Referenced by:** `expenses-module`

---

## Overview

UI spec for tenant expense configuration. Spec 17 (`expenses-module`) § "Tenant Configuration" defines the data model (fields stored in `tenant_settings` JSONB) and briefly lists the available settings. This spec fills in the full UI implementation.

Route: `/settings/expenses`  
Permission: `settings:write`

---

## Page: `/settings/expenses`

```
┌────────────────────────────────────────────────────────────┐
│  Settings / Expenses                                       │
│                                                            │
│  ── General ────────────────────────────────────────────── │
│                                                            │
│  Default Category                                          │
│  Applied when AI cannot determine category                 │
│  [Other business expenses ▾]                               │
│                                                            │
│  Auto-approve threshold                                    │
│  AI evaluations below this amount are auto-accepted        │
│  ₪ [500______]   (0 = manual review for all)              │
│                                                            │
│  ── VAT Reporting ─────────────────────────────────────── │
│                                                            │
│  VAT Report Period                                         │
│  Determines PCN874 grouping in expense reports             │
│  ○ Monthly    ● Bimonthly                                  │
│                                                            │
│  ── Receipt Intake ─────────────────────────────────────── │
│                                                            │
│  Email Receipt Forwarding                                  │
│  Forward receipts to this address for auto-import         │
│  [expenses@acme.zync.is]            [Copy]                  │
│  (read-only — generated from your workspace slug)         │
│                                                            │
│  Receipt Reminders                                         │
│  Send reminders for expenses missing receipts             │
│  ● Enabled    ○ Disabled                                   │
│  Remind after: [7___] days without a receipt attached     │
│                                                            │
│  ── Approval (Business+ only) ───────────────────────────── │
│                                                            │
│  Require approval for expenses above                       │
│  ₪ [0_______]   (0 = approval required for all)          │
│  Approver: [Any Admin ▾]                                   │
│  ⓘ Available on Business+ plan                            │
│                                                            │
│                              [Save Changes]                │
└────────────────────────────────────────────────────────────┘
```

---

## Field Reference

| Field | Stored in | Default | Notes |
|-------|-----------|---------|-------|
| Default category | `tenant_settings.expense_default_category` | `other` | 8 IL tax categories from `packages/types/src/expense-categories.ts` |
| Auto-approve threshold | `tenant_settings.expense_auto_approve_threshold_ils` | `0` (disabled) | ILS integer; AI confidence ≥ 80% + amount < threshold → auto-accepted |
| VAT period | `tenant_settings.vat_report_period` | `monthly` | `monthly` \| `bimonthly` |
| Email forwarding | derived from `tenants.slug` | — | Read-only; format `expenses@{slug}.zync.is`; explained in spec 17 email intake section |
| Receipt reminders | `tenant_settings.expense_receipt_reminder_enabled` + `_days` | disabled, 7 days | Cron sends reminder to `created_by` user |
| Approval threshold | `tenant_settings.expense_approval_threshold_ils` | `0` (all require approval) | **Business+ only** — rendered but disabled (with upgrade prompt) on Freelancer tier; see spec 65 |
| Approver | `tenant_settings.expense_approver_role` | `any_admin` | **Business+ only** — `any_admin` \| specific `user_id` |

---

## Save Behavior

All fields saved together on "Save Changes" button: `PATCH /api/settings/expenses` with the full settings object.  
Validation: threshold fields must be non-negative integers. Period must be `monthly` or `bimonthly`.  
On success: toast "Expense settings saved".

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Email forwarding read-only | Not configurable | Address derived from tenant slug; customizing it would require per-address email routing config — unnecessary complexity |
| Approval threshold 0 = all | Not `null` = disabled | Explicit: 0 means "every expense needs approval"; null would be ambiguous. Consistent with auto-approve threshold convention |
| Single PATCH for all fields | Not field-by-field | Settings are low-write (changed rarely); atomic save reduces partial-update confusion; avoids debounce complexity |