# Invoice Settings Page

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

---

## Overview

Spec 15 (`invoices-core`) defines `tenant_settings` columns like `default_payment_terms_days` and `default_tax_rate` but has no UI to configure them. Spec 107 adds further defaults. This spec defines `/settings/invoicing` — the settings page for all invoice-related tenant configuration.

---

## Route

`/settings/invoicing` — admin only.

---

## Page Layout

```
┌──────────────────────────────────────────────────────────────┐
│  Settings > Invoicing                                        │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Invoice Defaults                                        │ │
│  │                                                          │ │
│  │  Default payment terms   [30] days after issue date      │ │
│  │  Default VAT/tax rate    [18] % (0.18 = 18%)            │ │
│  │  Currency                [ILS ▾]                         │ │
│  │  Invoice number prefix   [INV-______________]            │ │
│  │                                                          │ │
│  │  [Save]                                                  │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  IL Compliance                                           │ │
│  │                                                          │ │
│  │  Business type      [עוסק מ��רשה ▾]                       │ │
│  │  Business ID (ח.פ.) [___________]                        │ │
│  │  VAT registration # [___________]  (if applicable)      │ │
│  │                                                          │ │
│  │  Issue as tax invoices (חשבונית מס)   ● Yes  ○ No        │ │
│  │  Proforma prefix                      [PROFORMA-_______] │ │
│  │                                                          │ │
│  │  [Save]                                                  │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Late Payments                                           │ │
│  │                                                          │ │
│  │  Late payment fee    ○ None  ● Flat amount  ○ Percentage │ │
│  │  Fee amount          [₪50___]                            │ │
│  │  Applies after       [30] days overdue                   │ │
│  │                                                          │ │
│  │  [Save]                                                  │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Invoice Appearance                                      │ │
│  │                                                          │ │
│  │  Logo               [Current logo] [Change]             │ │
│  │  Footer text        [___________________________]        │ │
│  │                     Appears at bottom of PDF invoices    │ │
│  │  Show payment link  ☑ Include pay-now link in sent emails│ │
│  │                                                          │ │
│  │  [Save]                                                  │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```

Each card saves independently with its own **[Save]** button.

---

## Settings Backed By

These settings use existing or new `tenant_settings` columns:

| Setting | Column | Default |
|---------|--------|---------|
| Default payment terms | `default_payment_terms_days` | `30` |
| Default VAT rate | `default_tax_rate` | `0.18` |
| Currency | `default_currency` (new) | `'ILS'` |
| Invoice number prefix | `invoice_number_prefix` (new) | `'INV-'` |
| Business type | `business_type` (existing in tenants) | — |
| Issue as tax invoices | `issue_tax_invoices` (new) | `true` |
| Proforma prefix | `proforma_number_prefix` (new) | `'PROFORMA-'` |
| Late fee type | `late_fee_type` (new) | `'none'` |
| Late fee amount | `late_fee_amount` (new) | `null` |
| Late fee threshold days | `late_fee_threshold_days` (new) | `30` |
| Footer text | `invoice_footer_text` (new) | `null` |
| Show payment link | `invoice_show_payment_link` (new) | `true` |

---

## Schema Delta

```sql
-- default_payment_terms_days is owned by invoices-core (wave 6, the invoice domain owner);
-- this page consumes/edits it but does NOT add it here.
ALTER TABLE tenant_settings
  ADD COLUMN default_tax_rate NUMERIC(5,4) NOT NULL DEFAULT 0.18,
  ADD COLUMN invoice_number_prefix TEXT NOT NULL DEFAULT 'INV-',
  ADD COLUMN issue_tax_invoices BOOLEAN NOT NULL DEFAULT true,
  ADD COLUMN proforma_number_prefix TEXT NOT NULL DEFAULT 'PROFORMA-',
  ADD COLUMN late_fee_type TEXT NOT NULL DEFAULT 'none'
    CHECK (late_fee_type IN ('none', 'flat', 'percentage')),
  ADD COLUMN late_fee_amount NUMERIC(10,2),
  ADD COLUMN late_fee_threshold_days INTEGER DEFAULT 30,
  ADD COLUMN invoice_footer_text TEXT,
  ADD COLUMN invoice_show_payment_link BOOLEAN NOT NULL DEFAULT true;
```

Note: this spec is sole owner of `default_tax_rate` (spec 107 / proposal-to-invoice-direct only consumes it); `default_payment_terms_days` is owned by `invoices-core` and only consumed/edited here. `default_currency` is NOT a `tenant_settings` column — it is the `tenants.default_currency` scalar (system-i18n), surfaced read/write by the Invoice Defaults card.

---

## Effect on Invoice Creation

When a new invoice is created (any flow):
- `payment_terms_days` pre-filled from `tenant_settings.default_payment_terms_days`
- `tax_rate` line pre-filled from `tenant_settings.default_tax_rate`
- Invoice number generated with `tenant_settings.invoice_number_prefix` + sequence
- If `invoice_show_payment_link = true`, sent invoice email includes pay-now button (spec 53)

---

## API

```
GET /api/settings/invoicing
    → get invoice settings for tenant
      Requires: admin

PATCH /api/settings/invoicing
      body: { default_payment_terms_days?, default_tax_rate?, default_currency?,
              invoice_number_prefix?, issue_tax_invoices?, proforma_number_prefix?,
              late_fee_type?, late_fee_amount?, late_fee_threshold_days?,
              invoice_footer_text?, invoice_show_payment_link? }
      Requires: admin
```

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Separate `/settings/invoicing` route | Not under `/settings/business` | Invoice settings are operational defaults, not business identity; separate route allows permissions + mental model clarity |
| Per-card Save | Not single page Save | Settings cards are independent; partial save avoids losing unrelated changes if one section has validation errors |
| All in tenant_settings | Not new settings table | `tenant_settings` is the canonical KV store for tenant config; no new table needed |
| `invoice_number_prefix` | Not auto-detect from existing invoices | Prefix is a deliberate business choice; auto-detection could be wrong; explicit is safer |