Multi-Currency Management

BillHive supports multi-currency billing, allowing tenants to operate in their preferred base currency while managing subscriptions, invoices, and payments across multiple currencies. The platform handles exchange rate ingestion, currency conversion, and consolidated reporting automatically.

Key Concepts

Concept	Description
Base Currency	The tenant’s primary currency used for consolidated reporting and analytics. Stored on the tenant record as `base_currency_code`.
Account Currency	The billing currency assigned to a customer account. Locked after the first invoice is generated to maintain ledger consistency.
Exchange Rate	The conversion factor between a base currency and a target currency, fetched automatically from an external provider.
Currency Conversion	The process of normalizing monetary amounts to the tenant’s base currency for reporting and analytics.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Currency Management Flow                      │
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────────────┐  │
│  │  Exchange     │    │  Currency     │    │  Analytics &      │  │
│  │  Rate Sync    │───>│  Conversions  │───>│  Reporting        │  │
│  │  (Batch)      │    │  Table        │    │  (SQL CTEs)       │  │
│  └──────────────┘    └──────────────┘    └───────────────────┘  │
│         │                                                        │
│         v                                                        │
│  ┌──────────────┐    ┌──────────────┐                           │
│  │  OpenExchange │    │  Subscription │                          │
│  │  Rates API    │    │  .currency    │                          │
│  └──────────────┘    └──────────────┘                           │
└─────────────────────────────────────────────────────────────────┘

Supported Currencies

BillHive currently supports the following currencies:

Code	Currency
USD	US Dollar
INR	Indian Rupee
CAD	Canadian Dollar
GBP	British Pound
AUD	Australian Dollar
EUR	Euro

How It Works

Tenant Setup — When a tenant configures their first (base) currency in BillHive, it is automatically stored as the tenant’s base_currency_code. Additional currencies can be added with their conversion rates.
Exchange Rate Sync — A batch service runs every 6 hours, fetching the latest exchange rates from OpenExchangeRates and persisting them to the currency_conversions table.
Account Currency Assignment — When an account is created, a currency is assigned (defaults to USD if not specified). Once the first invoice is generated for an account, the currency is locked and cannot be changed.
Order Validation — At order placement, BillHive validates that the order currency matches the account currency to prevent currency mismatches.
Reporting & Analytics — All analytics queries that aggregate monetary amounts apply currency conversion using the tenant’s configured rates, normalizing everything to the base currency for consistent dashboards.

Database Tables

Table	Schema	Purpose
`subscription.currency`	subscription	Stores per-tenant currencies with `conversion_rate`, `is_base_currency` flag, and `base_currency_code`
`currency_conversions`	subscription	Stores exchange rates fetched from the external provider (`base_currency`, `target_currency`, `exchange_rate`)
`user_tenant.tenant`	user_tenant	Holds the tenant’s `base_currency_code` for quick access in analytics queries

Conversion Formula

All analytics queries use the following conversion approach:

amount_in_base_currency = amount / COALESCE(conversion_rate, 1)

Where conversion_rate represents the number of target currency units per 1 unit of the base currency. If no rate is found, a fallback of 1 is used (assumes same currency).

Customer Entitlements Exchange Rate Sync