feat(billing): gate multi-currency billing behind ENABLE_MULTI_CURRENCY_BILLING toggle

app/views/api/v1/models/_account.json.jbuilder

@@ -6,7 +6,7 @@ if resource.custom_attributes.present?
     json.subscribed_quantity resource.custom_attributes['subscribed_quantity']
     json.subscription_status resource.custom_attributes['subscription_status']
     json.subscription_ends_on resource.custom_attributes['subscription_ends_on']
-    json.billing_currency resource.billing_currency if resource.respond_to?(:billing_currency)
+    json.billing_currency resource.billing_currency if resource.respond_to?(:billing_currency) && Enterprise::Billing::Currencies.enabled?
     json.website resource.custom_attributes['website'] if resource.custom_attributes['website'].present?
     json.industry resource.custom_attributes['industry'] if resource.custom_attributes['industry'].present?
     json.company_size resource.custom_attributes['company_size'] if resource.custom_attributes['company_size'].present?

config/installation_config.yml

@@ -258,6 +258,12 @@
   value: {}
   description: 'Currency-keyed AI credit top-up packages, e.g. {"usd":[{"credits":1000,"amount":20.0}],"brl":[{"credits":1000,"amount":100.0}]}'
   type: code
+- name: ENABLE_MULTI_CURRENCY_BILLING
+  display_title: 'Enable Multi-currency Billing'
+  value: false
+  locked: false
+  description: 'Bill new accounts in their local currency (e.g. BRL) and show currency-aware credit top-ups; when off, everyone is billed in USD'
+  type: boolean
 - name: CHATWOOT_CLOUD_PLAN_FEATURES
   display_title: 'Planwise Features List'
   value:

enterprise/app/models/enterprise/account.rb

@@ -69,6 +69,9 @@ module Enterprise::Account
   end
 
   def billing_currency
+    # Feature off => everyone is billed in USD (legacy behaviour).
+    return Enterprise::Billing::Currencies::DEFAULT unless Enterprise::Billing::Currencies.enabled?
+
     stored = custom_attributes&.dig('billing_currency')
     return Enterprise::Billing::Currencies.normalize(stored) if Enterprise::Billing::Currencies.supported?(stored)
 

enterprise/app/services/enterprise/billing/currencies.rb

@@ -4,6 +4,8 @@ module Enterprise::Billing::Currencies
 
   SUPPORTED = %w[usd brl].freeze
 
+  FEATURE_CONFIG = 'ENABLE_MULTI_CURRENCY_BILLING'.freeze
+
   # Account locale label (e.g. 'pt_BR') => default currency; unlisted falls back to DEFAULT.
   LOCALE_DEFAULTS = {
     'pt_BR' => 'brl'
@@ -21,6 +23,11 @@ module Enterprise::Billing::Currencies
 
   module_function
 
+  # Master switch for the whole multi-currency feature; off => everyone is billed in USD.
+  def enabled?
+    GlobalConfigService.load(FEATURE_CONFIG, 'false').to_s != 'false'
+  end
+
   def normalize(code)
     code.to_s.strip.downcase.presence
   end

spec/enterprise/services/enterprise/billing/create_stripe_customer_service_spec.rb

@@ -118,17 +118,19 @@ describe Enterprise::Billing::CreateStripeCustomerService do
     end
 
     it 'sets the billing country override when the account currency requires it' do
-      account.update!(custom_attributes: { billing_currency: 'brl' })
-      customer = double
-      allow(Stripe::Customer).to receive(:create).and_return(customer)
-      allow(customer).to receive(:id).and_return('cus_random_number')
-      allow(Stripe::Subscription).to receive(:create).and_return(created_subscription)
+      with_modified_env ENABLE_MULTI_CURRENCY_BILLING: 'true' do
+        account.update!(custom_attributes: { billing_currency: 'brl' })
+        customer = double
+        allow(Stripe::Customer).to receive(:create).and_return(customer)
+        allow(customer).to receive(:id).and_return('cus_random_number')
+        allow(Stripe::Subscription).to receive(:create).and_return(created_subscription)
 
-      create_stripe_customer_service.new(account: account).perform
+        create_stripe_customer_service.new(account: account).perform
 
-      expect(Stripe::Customer).to have_received(:create).with(
-        { name: account.name, email: admin1.email, address: { country: 'BR' }, preferred_locales: ['pt-BR'] }
-      )
+        expect(Stripe::Customer).to have_received(:create).with(
+          { name: account.name, email: admin1.email, address: { country: 'BR' }, preferred_locales: ['pt-BR'] }
+        )
+      end
     end
   end