🏦 Accounting-Grade Currency Architecture

Base Currency / Invoice Currency Separation: The system maintains a clear distinction between two currency contexts: the Base Currency (the agency’s internal accounting currency, e.g., CAD) and the Invoice Currency (the client-facing billing currency, e.g., USD). Both are stored independently on every invoice.
Exchange Rate Locking at Issuance: When an invoice transitions from draft to issued status, the prevailing exchange rate is permanently locked and stored as _invoice_exchange_rate_locked. This rate never changes, ensuring historical invoice values remain accurate regardless of future market movements — consistent with how systems like Xero, QuickBooks, and Stripe Invoicing operate.
Dual-Value Invoice Storage: Each invoice stores both its totals in the invoice (client) currency and the equivalent base-currency values calculated at the locked rate, guaranteeing accounting consistency across all reporting periods.
Base Currency Post Meta: The base currency code at the time of issuance is saved directly on the invoice (_invoice_base_currency), creating a complete, self-contained record that does not depend on future system defaults.
Immutable Issued Invoice Currency: Once an invoice has been issued (status unpaid, partial, or paid), the currency metabox switches to a read-only display. The currency selector is intentionally disabled to prevent retroactive modification of financial records.

💱 FX Rate Sourcing & Conversion Cost Tracking

Live-First, Manual-Fallback Rate Resolution: The system first attempts a live lookup via the Agency Pulse API. If unavailable, it automatically falls back to the manually configured rate stored in currency settings, ensuring a rate is always available.
Payment FX Tracking Hook: Exposes the apapi_get_exchange_rate_for_invoice filter, called by gateway and payment modules when recording a payment, enabling downstream FX gain/loss calculation.
Base Currency Conversion API: The apapi_convert_invoice_to_base filter accepts an amount and currency pair, returning the equivalent base-currency value for admin dashboards that display dual-currency totals.
Rate Source Transparency: The get_rate_for_invoice() service method returns both the rate and its source (live, manual, same_currency, or fallback), allowing the system to record how a rate was determined at the time of lock.

Unlimited Currency Support: Add and manage any world currency within the system using standard ISO 4217 codes (e.g., USD, EUR, GBP, JPY).
Customizable Formatting: Define unique symbols, decimal precision, and symbol positioning (before/after amount) for every active currency.
System-Wide Base Currency: Designate one currency as the primary base for the agency’s accounting. All conversion and reporting logic references this currency as the anchor.
Dynamic AJAX Management: Add, edit, or remove currencies instantly from the admin dashboard without page reloads.
World Currency Search (requires Pro API connector): Search and auto-populate currency fields from a global database of world currencies including correct symbols, decimal precision, and positioning rules.

Live Rate Synchronization (requires Pro API connector): Connects to the Agency Pulse API service to fetch current market exchange rates for precise currency conversion at the moment of invoice creation.
Intelligent Caching: Implements a transient-based caching layer for exchange rate lookups. Cache TTL is driven by the API response’s cached_for_seconds value to balance freshness with API call efficiency.
Manual Rate Override: Each currency carries a configurable manual exchange rate relative to the base currency — serving as both the primary rate source when the API is unavailable and as the administrator’s override mechanism for fixed-rate billing.
Developer Debug Mode: Define APMC_DISABLE_EXCHANGE_CACHE = true to force live rate lookups on every request, bypassing transient caches during testing or critical billing adjustments.

Per-Client Currency Assignment: Assign a preferred billing currency to each client via the Agency Pulse Portal. New invoices for that client automatically inherit the assigned currency.
Smart Country-to-Currency Mapping: The system suggests the most likely currency for a client automatically based on their selected country in the portal interface, reducing manual data entry.
Portal Integration Layer: Deeply integrates currency selection into both the client creation and edit workflows of the Agency Pulse Portal plugin, including a live-populated currency selector driven by configured currencies.
Persistent Client Metadata: Stores currency preferences as _client_currency post meta to ensure portability and consistent reference across the entire ecosystem.

Draft-Stage Currency Selection: For invoices in draft status, a Currency metabox in the invoice editor presents a full dropdown of configured currencies, allowing selection before the rate is locked.
Client Currency Auto-Sync: A dedicated JavaScript module (client-currency-sync.js) listens for client selection events in the invoice builder and automatically pre-selects the client’s assigned currency.
Formatted Totals Injection: Hooks into the core rendering engine (apapi_invoice_display_total, apapi_invoice_display_tax_total) to display subtotals, tax lines, and grand totals with the correct symbol, decimal precision, and positioning.
Admin Dual-Currency Display: In the admin dashboard, invoice totals are shown in both the base currency and the invoice currency side-by-side (e.g., $1,420 CAD ($1,000 USD)), giving the agency a clear picture of both the client-facing amount and the internal accounting value.

APMC_Currency_Service Singleton: A dedicated service class providing currency data access, amount formatting, currency conversion, and live rate fetching independently of the WordPress UI layer. Designed for consumption by other plugins in the ecosystem.
Extensible Filter Suite: Provides hooks including apapi_get_base_currency, apapi_convert_invoice_to_base, apapi_get_exchange_rate_for_invoice, apapi_format_currency_amount, and agency_pulse_invoice_currency_symbol for deep integration by other system components.
AJAX-Powered Endpoints: Secure, nonce-protected AJAX endpoints for retrieving configured currencies, fetching live rates, suggesting currencies by country, and updating invoice currency metadata.
Security & Sanitization: Implements strict WordPress nonces and input validation for all currency-related operations, with capability checks (manage_options, edit_post) on all privileged endpoints.

Automatic Updates: The plugin includes a self-hosted update checker that connects to Agency Pulse licensing servers. New releases are detected automatically and can be installed directly from the standard WordPress plugins update screen.