PSA/ee/docs/plans/2025-11-17-multi-currency-billing-plan.md

Multi-Currency Billing Enablement Plan

Date: 2025-11-17
Author: Codex AI (billing pod)
Scope: All tenant-scoped billing, invoicing, ledger, reporting, and accounting export flows running in the monolith (server/*, shared/*, ee/*).

Executive Summary

• The public docs (docs/overview.md, docs/billing.md) promise multi-currency billing, yet the live code base still hardcodes USD across pricing tables, UI components, invoice templates, and accounting exports.
• Recent groundwork exists (e.g., migration 20251026120000_convert_invoice_and_transactions_currency.cjs adds invoices.currency_code + exchange_rate_basis_points, transactions.amount now stores cents), but the data is never populated and upstream pricing sources (service_catalog, contract line pricing, manual invoices) remain currency-agnostic.
• This plan delivers tenant-wide base currency configuration, per-client/contract currency overrides, deterministic FX snapshots per invoice, UI/template updates, reporting rollups, and adapter-safe exports while respecting existing rules (e.g., default invoice templates must flow through invoice_template_assignments per docs/AI_coding_standards.md).

Current State Assessment

Data & Persistence

• Money columns across service_catalog, contract_lines, client_contract_line_pricing, client_contract_services, client_contract_line_terms, invoices, invoice_charges, credit_tracking, and transactions are integer cents with no associated currency_code (see server/migrations/202409071803_initial_schema.cjs, 20241125124900_add_credit_system.cjs).
• invoices.currency_code / exchange_rate_basis_points exist but are always NULL because neither server/src/lib/billing/billingEngine.ts nor manual invoice flows set them.
• clients (renamed from companies in 20251003000001_company_to_client_migration.cjs) lack any currency preference columns; tenant_settings.settings has locale data but no monetary configuration (see server/migrations/20250630161508_create_tenant_settings_table.cjs).
• Accounting export tables (accounting_export_batches, accounting_export_lines) expect a currency_code (per ee/docs/plans/2025-10-26-accounting-export-abstraction-plan.md) but ingest-only sees defaults from selectors.

Application Logic

• BillingEngine.calculateBilling computes cents assuming tenant currency, with no awareness of client/contract currency or FX snapshots. Template cloning (server/src/lib/billing/utils/templateClone.ts) copies custom_rate numbers without currency context.
• Manual invoicing (server/src/lib/actions/manualInvoiceActions.ts, server/src/components/billing-dashboard/ManualInvoices.tsx) renders $ and never stores a currency_code.
• Invoice persistence/services (server/src/lib/services/invoiceService.ts, server/src/lib/models/invoice.ts, server/src/lib/actions/invoiceQueries.ts) neither read nor write currency metadata.
• Finalization & ledger flows (server/src/lib/actions/invoiceModification.ts, server/src/lib/actions/creditActions.ts, docs/invoice_finalization.md) make ledger entries in cents without knowing which currency they represent.

UI, Templates, and Client Portal

• Currency formatting is globally hard-coded to USD in server/src/lib/utils/formatters.ts, server/src/lib/i18n/server.ts, and UI layers such as ClientContractLineDashboard.tsx, contracts/ContractTemplateDetail.tsx, ManualInvoices.tsx, server/src/components/billing-dashboard/accounting/AccountingExportsTab.tsx, and client-portal surfaces (server/src/components/client-portal/billing/BillingOverview.tsx, client-portal/account/ClientAccount.tsx).
• Invoice template Wasm helpers (server/src/invoice-templates/assemblyscript/assembly/common/format-helpers.ts) prepend $ and the host WasmInvoiceViewModel (server/src/lib/invoice-renderer/types.ts) carries no currency metadata, so PDF generation (server/src/lib/actions/invoiceGeneration.ts) cannot localize values.

Reporting & Integrations

• Report definitions (server/src/lib/reports/definitions/billing/overview.ts, contracts/*.ts) and the core engine (server/src/lib/reports/core/ReportEngine.ts) always emit USD, making KPI dashboards incorrect for non-USD tenants.
• Accounting exports default to 'USD' (server/src/lib/services/accountingExportInvoiceSelector.ts, AccountingExportsTab.tsx) and only pass through invoice-level currency when available; adapters (server/src/lib/adapters/accounting/quickBooksOnlineAdapter.ts, .../xeroAdapter.ts) assume same-currency credits and ignore exchange-rate gaps noted in the accounting export plan.

Documentation Gap

• docs/billing.md, docs/billing_cycles.md, docs/invoice_templates.md, and docs/invoice_finalization.md make no mention of base currency resolution or FX handling even though marketing copy advertises multi-currency.

Goals & Non-Goals

• Goals: Tenant-level base currency selection, client/contract currency overrides, deterministic FX storage per invoice, UI/template formatting with ISO 4217 codes, ledger + credit handling in mixed currencies, reporting and export parity, strong migration/backfill + tests.
• Non-Goals: Implementing payment processor FX, exposing automated FX rate providers to end users, or redesigning invoice template assignment semantics (must continue via invoice_template_assignments).

Guiding Principles

1. Single Source of Truth: Base currency lives in tenant_settings.settings.billing.currency. Client/contract overrides cascade deterministically (tenant → client → contract → invoice).
2. Fail Fast (per docs): Billing services throw when currency context is missing instead of guessing.
3. Immutable FX Snapshots: Each invoice stores currency_code and exchange_rate_basis_points taken at generation time; charges inherit invoice currency.
4. Integer Math Everywhere: Continue storing cents; conversions happen via basis points to avoid floating precision issues.
5. Backwards-Compatible APIs: External consumers keep receiving integers but now also get explicit currency_code in DTOs.

Proposed Architecture

Currency Resolution Hierarchy

• Extend tenant_settings JSON to hold { billing: { baseCurrency: 'USD', supportedCurrencies: [...] } } managed by server/src/lib/actions/tenant-settings-actions/tenantSettingsActions.ts & locale actions.
• Add currency_code to clients, client_contracts, client_contract_lines, and contracts to capture overrides defined in docs/billing.md. Rates in service_catalog, contract_lines, and client_contract_line_pricing gain currency_code metadata so cloning + billing knows how to convert before charge generation.
• BillingEngine determines the invoice currency per client billing cycle (see docs/billing_cycles.md) and records it on invoices + invoice_charges (explicit column or derived join) while persisting exchange_rate_basis_points representing conversion to tenant base.

FX & Money Services

• Introduce fx_rates table storing (fx_rate_id, tenant, source_currency, target_currency, rate_basis_points, effective_at, provider, metadata) plus caching service server/src/lib/services/exchangeRateService.ts. Provide admin override UI later if needed.
• Add helper Money utilities in shared/utils and server/src/lib/utils/money.ts to normalize conversions, rounding, formatting (tying into server/src/lib/i18n/server.ts).

Ledger & Reporting Alignment

• Transactions, credit tracking, and analytics events store both invoice currency (currency_code) and converted base-cents (base_amount_cents). Reports roll up base amounts but also expose per-currency breakdown when filters require.
• Accounting exports continue to emit the invoice currency while also including base currency + exchange rate for GL mapping.

Templates & Rendering

• Extend WasmInvoiceViewModel with currencyCode, currencySymbol, and localized helpers. Update AssemblyScript helpers to accept a currency code argument rather than hardcoding $, following the instructions in docs/invoice_templates.md and ensuring default selection still respects invoice_template_assignments.

Implementation Plan

Phase 0 – Schema & Configuration Foundations (Week 1)

1. Tenant Settings:
   • Migration adding settings->billing scaffold plus admin actions to read/write base currency + supported list (server/src/lib/actions/tenant-actions/tenantSettingsActions.ts, tenantLocaleActions.ts).
   • UI stub (likely under server/src/components/settings/general if needed) to set currency.
2. Entity Columns:
   • Add currency_code columns + composite indexes to clients, client_contracts, client_contract_lines, contracts, service_catalog, client_contract_line_pricing, client_contract_services, and invoice_charges (even if it mirrors invoice currency for clarity) via new Knex migration.
   • Backfill existing rows: default to tenant base currency (fall back to 'USD' until admin sets it).
3. Ledger Tables:
   • Extend transactions, credit_tracking, and client_credits with currency_code + optional base_amount_cents columns to prep for FX-aware credits described in docs/invoice_finalization.md.
4. Shared Types:
   • Update shared/interfaces/client.interfaces.ts, server/src/interfaces/*.ts (billing, invoice, contract, client) to include currency metadata. Ensure API controllers and Zod schemas (if any) accept the new fields.

Phase 1 – Billing & Invoice Generation Logic (Weeks 2-3)

1. Currency Resolution Service:
   • Build resolveCurrencyForClient(clientId) that walks tenant → client → contract line overrides, returning { currencyCode, exchangeRateBasisPoints } (uses ExchangeRateService).
2. Billing Engine Updates:
   • Inject currency context into BillingEngine so that calculateBilling populates invoice + charge currency fields, stores FX snapshot on invoices, and ensures all downstream calculations stay integer (update server/src/lib/billing/billingEngine.ts and supporting repos/queries).
   • Update template cloning (server/src/lib/billing/utils/templateClone.ts) and contract actions to persist rate currencies when copying from templates.
3. Manual + Automated Invoice Paths:
   • Extend manual invoice actions (manualInvoiceActions.ts, invoiceService.ts) to require currency_code, persist it on the invoice row, and surface currency selection in the UI (ManualInvoices.tsx, LineItem.tsx). Respect component ID guidelines when adding new selects.
   • Update invoice generation pipeline (server/src/lib/actions/invoiceGeneration.ts) so PDF/download flows include currency metadata in InvoiceViewModel and Wasm payloads.
4. Finalization & Credits:
   • Modify finalizeInvoice/unfinalizeInvoice + creditActions.ts to store ledger entries with both invoice and base currency amounts, handling FX gains/losses via the existing currency_adjustment transaction type.

Phase 2 – UI, Templates, and Client Portal (Weeks 3-4)

1. Shared Formatting Utilities:
   • Replace ad-hoc USD formatting with a centralized formatMoney(amountCents, currencyCode, locale) exported from server/src/lib/utils/formatters.ts and server/src/lib/i18n/server.ts. Update consumers in billing dashboard cards, contract UIs, AccountingExportsTab.tsx, and report components.
2. Client Portal + Billing Dashboard:
   • Propagate currency down to BillingOverview.tsx, ContractLineDetailsDialog.tsx, client-portal/account/ClientAccount.tsx, and invoice tables under server/src/components/billing-dashboard/invoicing/*.tsx so that drafts/finalized lists display currency_code badges and totals.
   • Ensure manual invoice UI, contract forms, and service configuration editors show the correct currency next to rate inputs (without renaming existing fields) and allow switching currency only where permissible (likely at client/contract level, not per line item).
3. Invoice Templates & Renderer:
   • Update server/src/lib/invoice-renderer/types.ts, wasm-executor.ts, and AssemblyScript helpers to pass currency metadata to templates. Replace $ in format-helpers.ts with dynamic symbol/resolved code. Update standard template sources under server/src/invoice-templates/assemblyscript/standard/* and re-run syncStandardTemplates per docs/invoice_templates.md.
   • Confirm InvoiceTemplateEditor.tsx surfaces currency references (maybe highlight preview currency based on selected invoice).

Phase 3 – Reporting, Analytics, and Integrations (Weeks 4-5)

1. Reporting Layer:
   • Teach ReportEngine (server/src/lib/reports/core/ReportEngine.ts) to read currency metadata from metrics. Update billing + contract report definitions to either (a) convert to tenant base currency using stored exchange rates or (b) emit multi-series metrics grouped by currency. Update docs/billing.md accordingly.
2. Accounting Exports:
   • Ensure selector (server/src/lib/services/accountingExportInvoiceSelector.ts) pulls invoices.currency_code and exchange_rate_basis_points, defaulting only when absent. Update UI (AccountingExportsTab.tsx) to display multi-currency totals, and include FX data in batch detail drawers.
   • Update adapters for QuickBooks/Xero to handle currency mismatches, leveraging helper conversions and new repository fields (server/src/lib/repositories/accountingExportRepository.ts).
3. API/Client Surfaces:
   • Propagate currency fields through REST controllers (server/src/lib/api/controllers/ApiAccountingExportController.ts, report-actions/getRecentClientInvoices.ts, etc.) and ensure client portal APIs (Next.js routes) include currency_code for invoice payloads.

Phase 4 – Testing, Backfill, and Rollout (Week 6)

1. Testing:
   • Unit tests for money utilities, currency resolution, and FX snapshots.
   • Integration tests: billing run with mixed currencies, invoice finalization applying credits across FX, accounting export batch containing multi-c invoices (server/src/test/integration/accounting/*).
   • E2E/Playwright updates in ee/server/src/__tests__/integration/batch-lifecycle.playwright.test.ts to cover UI filtering/rendering with multiple currencies.
2. Backfill + Scripts:
   • Write one-time script (e.g., scripts/backfill-invoice-currency.ts) to set currency_code/exchange_rate on existing invoices using tenant default + rate 1.0.
   • Provide validation script to compare totals between old/new representations (ensuring ledger balances).
3. Rollout Controls:
   • Feature flag (env or tenant_settings) gating UI display + FX enforcement until migrations complete.
   • Monitoring: add PostHog analytics events enriched with currency_code for invoice generation/finalization so we can verify adoption.

Risks & Mitigations

• Historical Data Accuracy: Backfilling legacy invoices with assumed USD may not match actual currency; surface a per-tenant override tool and audit report to identify invoices where manual correction is needed.
• FX Source Reliability: Decide on provider (manual entry vs. API). Mitigate by allowing manual overrides and caching resolved rates alongside provider metadata.
• UI Complexity: Introducing currency selectors everywhere may overwhelm users; limit editing to tenant/client settings and surface read-only badges elsewhere.
• Downstream Integrations: QuickBooks/Xero realm currencies may reject mismatched codes; enforce validation in adapters before batch creation and raise actionable errors in AccountingExportsTab.tsx.

Open Questions / Decisions Needed

1. Do we support mixed currencies within a single tenant simultaneously, or enforce one invoice currency per client? (Plan assumes per-client/per-contract override but not per line item.)
2. What is the authoritative exchange-rate provider (internal manual table vs. external API)?
3. Should transactions.amount remain invoice currency while base_amount_cents stores tenant currency, or should we flip (base in amount, invoice in extras)?
4. How should credit balances behave when applying a USD credit to a CAD invoice—immediate FX conversion or split ledgers?

Success Metrics

• 100% of new invoices carry non-null currency_code + exchange_rate_basis_points.
• Accounting export batches show accurate multi-currency totals and pass adapter validation for QuickBooks & Xero.
• Billing + contract reports display correct totals when at least two currencies exist in tenant data.
• Manual invoicing UI allows selecting/displaying non-USD currencies without regression failures.

Documentation & Follow-ups

• Update docs/billing.md, docs/billing_cycles.md, docs/invoice_finalization.md, and docs/invoice_templates.md to document currency hierarchy and FX handling.
• Document admin workflows in docs/billing.md + customer portal references.
• Ensure release notes highlight required migrations and manual steps for self-hosted tenants.