✨ feat(ui): add billing type editor to provider settings

Provider settings modal now includes:
- Billing Type dropdown: Pay-per-use / Subscription / Free
- Subscription fields: Monthly Cost (USD) + Plan Name (conditional)
- Billing badges on provider cards: violet "Subscription $20/mo", green "Free"

Backend:
- user_provider_configs table gains billing columns (migration 024)
- Provider routes return billingType in list + detail responses
- Validation schema accepts billingType, subscriptionCostUsd, subscriptionPlan
- Local + CLI providers default to 'free'

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ersinkoc

packages/gateway/src/db/migrations/postgres/001_initial_schema.sql

@@ -633,6 +633,9 @@ CREATE TABLE IF NOT EXISTS user_provider_configs (
   is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
   api_key_env TEXT,
   notes TEXT,
+  billing_type TEXT NOT NULL DEFAULT 'pay-per-use',
+  subscription_cost_usd REAL,
+  subscription_plan TEXT,
   config JSONB DEFAULT '{}',
   created_at TIMESTAMP NOT NULL DEFAULT NOW(),
   updated_at TIMESTAMP NOT NULL DEFAULT NOW(),

packages/gateway/src/db/migrations/postgres/024_provider_billing.sql

@@ -7,7 +7,16 @@ ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS subscription_cost_usd REAL
 ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS subscription_plan TEXT;
 ALTER TABLE custom_providers ADD COLUMN IF NOT EXISTS billing_notes TEXT;
 
+-- Add billing columns to user_provider_configs (built-in provider overrides)
+ALTER TABLE user_provider_configs ADD COLUMN IF NOT EXISTS billing_type TEXT NOT NULL DEFAULT 'pay-per-use';
+ALTER TABLE user_provider_configs ADD COLUMN IF NOT EXISTS subscription_cost_usd REAL;
+ALTER TABLE user_provider_configs ADD COLUMN IF NOT EXISTS subscription_plan TEXT;
+
 -- Set known free providers
 UPDATE custom_providers SET billing_type = 'free'
 WHERE provider_id IN ('local', 'ollama', 'lmstudio', 'localai', 'vllm')
   AND billing_type = 'pay-per-use';
+
+UPDATE user_provider_configs SET billing_type = 'free'
+WHERE provider_id IN ('local', 'ollama', 'lmstudio', 'localai', 'vllm')
+  AND billing_type = 'pay-per-use';

packages/gateway/src/db/repositories/model-configs.ts

@@ -100,6 +100,9 @@ export interface UserProviderConfig {
   isEnabled: boolean;
   apiKeyEnv?: string;
   notes?: string;
+  billingType: 'pay-per-use' | 'subscription' | 'free';
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
   config: Record<string, unknown>;
   createdAt: Date;
   updatedAt: Date;
@@ -196,6 +199,9 @@ interface UserProviderConfigRow {
   is_enabled: boolean;
   api_key_env: string | null;
   notes: string | null;
+  billing_type: string | null;
+  subscription_cost_usd: number | null;
+  subscription_plan: string | null;
   config: string;
   created_at: string;
   updated_at: string;
@@ -247,6 +253,7 @@ function rowToProvider(row: CustomProviderRow): CustomProvider {
 }
 
 function rowToUserProviderConfig(row: UserProviderConfigRow): UserProviderConfig {
+  const billingType = row.billing_type as UserProviderConfig['billingType'] | null;
   return {
     id: row.id,
     userId: row.user_id,
@@ -256,6 +263,9 @@ function rowToUserProviderConfig(row: UserProviderConfigRow): UserProviderConfig
     isEnabled: row.is_enabled,
     apiKeyEnv: row.api_key_env || undefined,
     notes: row.notes || undefined,
+    billingType: billingType ?? 'pay-per-use',
+    subscriptionCostUsd: row.subscription_cost_usd ?? undefined,
+    subscriptionPlan: row.subscription_plan ?? undefined,
     config: parseJsonField(row.config, {}),
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at),

packages/gateway/src/middleware/validation.ts

@@ -526,6 +526,9 @@ export const providerConfigSchema = z.object({
   isEnabled: z.boolean().optional(),
   apiKeyEnv: z.string().max(200).optional(),
   notes: z.string().max(2000).optional(),
+  billingType: z.enum(['pay-per-use', 'subscription', 'free']).optional(),
+  subscriptionCostUsd: z.number().min(0).max(10000).optional(),
+  subscriptionPlan: z.string().max(200).optional(),
 });
 
 // ─── Workspace File & Execute Schemas ───────────────────────────

packages/gateway/src/routes/providers.ts

@@ -257,6 +257,10 @@ app.get('/', async (c) => {
       isEnabled: override?.isEnabled !== false,
       // Has user override
       hasOverride: !!override,
+      // Billing
+      billingType: override?.billingType ?? 'pay-per-use',
+      subscriptionCostUsd: override?.subscriptionCostUsd,
+      subscriptionPlan: override?.subscriptionPlan,
       // Configuration source: 'database' = set via UI, 'environment' = set via env var
       configSource,
       // UI metadata
@@ -298,6 +302,9 @@ app.get('/', async (c) => {
       isConfigured: true,
       isEnabled: true,
       hasOverride: false,
+      billingType: 'free' as const,
+      subscriptionCostUsd: undefined,
+      subscriptionPlan: undefined,
       configSource: 'database' as const,
       color: localProviderColors[lp.providerType] ?? '#10b981',
       apiKeyPlaceholder: undefined,
@@ -331,6 +338,9 @@ app.get('/', async (c) => {
       isConfigured: cli.authenticated,
       isEnabled: true,
       hasOverride: false,
+      billingType: 'free' as const,
+      subscriptionCostUsd: undefined,
+      subscriptionPlan: undefined,
       configSource: 'database' as const, // CLI providers are auto-detected
       color: cliProviderColors[cli.id] ?? '#666666',
       apiKeyPlaceholder: undefined,
@@ -423,13 +433,19 @@ app.get('/:id', async (c) => {
     isEnabled: override?.isEnabled !== false,
     hasOverride: !!override,
     // Include user override details if present
+    billingType: override?.billingType ?? 'pay-per-use',
+    subscriptionCostUsd: override?.subscriptionCostUsd,
+    subscriptionPlan: override?.subscriptionPlan,
     userOverride: override
       ? {
           baseUrl: override.baseUrl,
           providerType: override.providerType,
           isEnabled: override.isEnabled,
           apiKeyEnv: override.apiKeyEnv,
           notes: override.notes,
+          billingType: override.billingType,
+          subscriptionCostUsd: override.subscriptionCostUsd,
+          subscriptionPlan: override.subscriptionPlan,
         }
       : null,
     // UI metadata

packages/ui/src/components/ProvidersTab.tsx

@@ -37,11 +37,15 @@ export function ProvidersTab() {
     providerType: string;
     isEnabled: boolean;
     notes: string;
+    billingType?: 'pay-per-use' | 'subscription' | 'free';
+    subscriptionCostUsd?: number;
+    subscriptionPlan?: string;
   }>({
     baseUrl: '',
     providerType: '',
     isEnabled: true,
     notes: '',
+    billingType: 'pay-per-use',
   });
   const [saving, setSaving] = useState(false);
 
@@ -85,6 +89,9 @@ export function ProvidersTab() {
         providerType: override.providerType || (baseConfig as Record<string, string>).type || '',
         isEnabled: override.isEnabled !== false,
         notes: override.notes || '',
+        billingType: override.billingType ?? 'pay-per-use',
+        subscriptionCostUsd: override.subscriptionCostUsd,
+        subscriptionPlan: override.subscriptionPlan,
       });
       setEditingProvider(providerId);
     } catch {
@@ -101,6 +108,11 @@ export function ProvidersTab() {
         providerType: editForm.providerType || undefined,
         isEnabled: editForm.isEnabled,
         notes: editForm.notes || undefined,
+        billingType: editForm.billingType,
+        subscriptionCostUsd:
+          editForm.billingType === 'subscription' ? editForm.subscriptionCostUsd : undefined,
+        subscriptionPlan:
+          editForm.billingType === 'subscription' ? editForm.subscriptionPlan : undefined,
       });
       // Refresh providers
       await fetchProviders();
@@ -179,6 +191,17 @@ export function ProvidersTab() {
                   Override
                 </span>
               )}
+              {provider.billingType === 'subscription' && (
+                <span className="text-xs px-1.5 py-0.5 bg-violet-100 dark:bg-violet-900/30 text-violet-700 dark:text-violet-300 rounded">
+                  Subscription
+                  {provider.subscriptionCostUsd ? ` $${provider.subscriptionCostUsd}/mo` : ''}
+                </span>
+              )}
+              {provider.billingType === 'free' && (
+                <span className="text-xs px-1.5 py-0.5 bg-emerald-100 dark:bg-emerald-900/30 text-emerald-700 dark:text-emerald-300 rounded">
+                  Free
+                </span>
+              )}
             </div>
 
             <div className="text-xs text-gray-500 dark:text-gray-400 space-y-1">
@@ -433,6 +456,72 @@ export function ProvidersTab() {
                     className="w-full px-3 py-2 bg-white dark:bg-gray-700 border border-gray-200 dark:border-gray-600 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-primary/50"
                   />
                 </div>
+
+                {/* Billing Type */}
+                <div>
+                  <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                    Billing Type
+                  </label>
+                  <select
+                    value={editForm.billingType ?? 'pay-per-use'}
+                    onChange={(e) =>
+                      setEditForm((f) => ({ ...f, billingType: e.target.value as never }))
+                    }
+                    className="w-full px-3 py-2 bg-white dark:bg-gray-700 border border-gray-200 dark:border-gray-600 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-primary/50"
+                  >
+                    <option value="pay-per-use">Pay-per-use (API)</option>
+                    <option value="subscription">Subscription (flat monthly fee)</option>
+                    <option value="free">Free (local / free tier)</option>
+                  </select>
+                  <p className="mt-1 text-xs text-gray-500">
+                    Pay-per-use: billed per token. Subscription: fixed monthly fee, no per-token
+                    cost. Free: no cost.
+                  </p>
+                </div>
+
+                {/* Subscription details (only if subscription) */}
+                {editForm.billingType === 'subscription' && (
+                  <div className="grid grid-cols-2 gap-3">
+                    <div>
+                      <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                        Monthly Cost (USD)
+                      </label>
+                      <input
+                        type="number"
+                        step="0.01"
+                        min="0"
+                        value={editForm.subscriptionCostUsd ?? ''}
+                        onChange={(e) =>
+                          setEditForm((f) => ({
+                            ...f,
+                            subscriptionCostUsd: e.target.value
+                              ? parseFloat(e.target.value)
+                              : undefined,
+                          }))
+                        }
+                        placeholder="e.g. 20.00"
+                        className="w-full px-3 py-2 bg-white dark:bg-gray-700 border border-gray-200 dark:border-gray-600 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-primary/50"
+                      />
+                    </div>
+                    <div>
+                      <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                        Plan Name
+                      </label>
+                      <input
+                        type="text"
+                        value={editForm.subscriptionPlan ?? ''}
+                        onChange={(e) =>
+                          setEditForm((f) => ({
+                            ...f,
+                            subscriptionPlan: e.target.value || undefined,
+                          }))
+                        }
+                        placeholder="e.g. ChatGPT Plus"
+                        className="w-full px-3 py-2 bg-white dark:bg-gray-700 border border-gray-200 dark:border-gray-600 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-primary/50"
+                      />
+                    </div>
+                  </div>
+                )}
               </div>
 
               {/* Actions */}

packages/ui/src/types/models.ts

@@ -17,6 +17,9 @@ export interface ModelInfo {
   recommended?: boolean;
 }
 
+/** Billing type for AI providers */
+export type BillingType = 'pay-per-use' | 'subscription' | 'free';
+
 /** Full provider info as returned by /api/v1/providers */
 export interface ProviderInfo {
   id: string;
@@ -28,6 +31,9 @@ export interface ProviderInfo {
   isConfigured: boolean;
   isEnabled: boolean;
   hasOverride: boolean;
+  billingType?: BillingType;
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
   color?: string;
   modelCount: number;
   features: {
@@ -58,6 +64,9 @@ export interface UserOverride {
   isEnabled: boolean;
   apiKeyEnv?: string;
   notes?: string;
+  billingType?: BillingType;
+  subscriptionCostUsd?: number;
+  subscriptionPlan?: string;
 }
 
 /** Local provider (Ollama, LM Studio, etc.) */