Org billing (#1995)

* Add billing organization selection

Introduces support for selecting a billing organization for inference requests in HuggingChat. Adds a new billing section in application settings, updates user settings and API to store and validate the selected organization, and ensures requests are billed to the chosen organization by sending the X-HF-Bill-To header. Also updates environment and chart files to include the new OpenID scope required for billing.

* Update +page.svelte

* Remove billingOrganization from default settings

* Fix user settings creation and update test for findUser

The test for updateUser now passes a URL to findUser to match the updated function signature. Also, the updateUser function now inserts the full DEFAULT_SETTINGS object when creating default user settings, ensuring billingOrganization is included.

.env

@@ -34,7 +34,7 @@ COUPLE_SESSION_WITH_COOKIE_NAME=
 # when OPEN_ID is configured, users are required to login after the welcome modal
 OPENID_CLIENT_ID="" # You can set to "__CIMD__" for automatic oauth app creation when deployed, see https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
 OPENID_CLIENT_SECRET=
-OPENID_SCOPES="openid profile inference-api read-mcp"
+OPENID_SCOPES="openid profile inference-api read-mcp read-billing"
 USE_USER_TOKEN=
 AUTOMATIC_LOGIN=# if true authentication is required on all routes
 

chart/env/dev.yaml

@@ -38,7 +38,7 @@ ingressInternal:
 envVars:
   TEST: "test"
   COUPLE_SESSION_WITH_COOKIE_NAME: "token"
-  OPENID_SCOPES: "openid profile inference-api read-mcp"
+  OPENID_SCOPES: "openid profile inference-api read-mcp read-billing"
   USE_USER_TOKEN: "true"
   MCP_FORWARD_HF_USER_TOKEN: "true"
   AUTOMATIC_LOGIN: "false"

chart/env/prod.yaml

@@ -48,7 +48,7 @@ ingressInternal:
 
 envVars:
   COUPLE_SESSION_WITH_COOKIE_NAME: "token"
-  OPENID_SCOPES: "openid profile inference-api read-mcp"
+  OPENID_SCOPES: "openid profile inference-api read-mcp read-billing"
   USE_USER_TOKEN: "true"
   MCP_FORWARD_HF_USER_TOKEN: "true"
   AUTOMATIC_LOGIN: "false"

src/app.d.ts

@@ -13,6 +13,8 @@ declare global {
 			user?: User;
 			isAdmin: boolean;
 			token?: string;
+			/** Organization to bill inference requests to (from settings) */
+			billingOrganization?: string;
 		}
 
 		interface Error {

src/lib/server/api/authPlugin.ts

@@ -22,6 +22,7 @@ export const authPlugin = new Elysia({ name: "auth" }).derive(
 				user: auth?.user,
 				sessionId: auth?.sessionId,
 				isAdmin: auth?.isAdmin,
+				token: auth?.token,
 			},
 		};
 	}

src/lib/server/api/routes/groups/user.ts

@@ -6,6 +6,8 @@ import { authCondition } from "$lib/server/auth";
 import { models, validateModel } from "$lib/server/models";
 import { DEFAULT_SETTINGS, type SettingsEditable } from "$lib/types/Settings";
 import { z } from "zod";
+import { config } from "$lib/server/config";
+import { logger } from "$lib/server/logger";
 
 export const userGroup = new Elysia()
 	.use(authPlugin)
@@ -72,6 +74,7 @@ export const userGroup = new Elysia()
 					customPrompts: settings?.customPrompts ?? {},
 					multimodalOverrides: settings?.multimodalOverrides ?? {},
 					toolsOverrides: settings?.toolsOverrides ?? {},
+					billingOrganization: settings?.billingOrganization ?? undefined,
 				};
 			})
 			.post("/settings", async ({ locals, request }) => {
@@ -90,6 +93,7 @@ export const userGroup = new Elysia()
 						disableStream: z.boolean().default(false),
 						directPaste: z.boolean().default(false),
 						hidePromptExamples: z.record(z.boolean()).default({}),
+						billingOrganization: z.string().optional(),
 					})
 					.parse(body) satisfies SettingsEditable;
 
@@ -123,5 +127,79 @@ export const userGroup = new Elysia()
 					})
 					.toArray();
 				return reports;
+			})
+			.get("/billing-orgs", async ({ locals, set }) => {
+				// Only available for HuggingChat
+				if (!config.isHuggingChat) {
+					set.status = 404;
+					return { error: "Not available" };
+				}
+
+				// Requires authenticated user with OAuth token
+				if (!locals.user) {
+					set.status = 401;
+					return { error: "Login required" };
+				}
+
+				if (!locals.token) {
+					set.status = 401;
+					return { error: "OAuth token not available. Please log out and log back in." };
+				}
+
+				try {
+					// Fetch billing info from HuggingFace OAuth userinfo
+					const response = await fetch("https://huggingface.co/oauth/userinfo", {
+						headers: { Authorization: `Bearer ${locals.token}` },
+					});
+
+					if (!response.ok) {
+						logger.error(`Failed to fetch billing orgs: ${response.status}`);
+						set.status = 502;
+						return { error: "Failed to fetch billing information" };
+					}
+
+					const data = await response.json();
+
+					// Get user's current billingOrganization setting
+					const settings = await collections.settings.findOne(authCondition(locals));
+					const currentBillingOrg = settings?.billingOrganization;
+
+					// Filter orgs to only those with canPay: true
+					const billingOrgs = (data.orgs ?? [])
+						.filter((org: { canPay?: boolean }) => org.canPay === true)
+						.map((org: { sub: string; name: string; preferred_username: string }) => ({
+							sub: org.sub,
+							name: org.name,
+							preferred_username: org.preferred_username,
+						}));
+
+					// Check if current billing org is still valid
+					const isCurrentOrgValid =
+						!currentBillingOrg ||
+						billingOrgs.some(
+							(org: { preferred_username: string }) => org.preferred_username === currentBillingOrg
+						);
+
+					// If current billing org is no longer valid, clear it
+					if (!isCurrentOrgValid && currentBillingOrg) {
+						logger.info(
+							`Clearing invalid billingOrganization '${currentBillingOrg}' for user ${locals.user._id}`
+						);
+						await collections.settings.updateOne(authCondition(locals), {
+							$unset: { billingOrganization: "" },
+							$set: { updatedAt: new Date() },
+						});
+					}
+
+					return {
+						userCanPay: data.canPay ?? false,
+						organizations: billingOrgs,
+						currentBillingOrg: isCurrentOrgValid ? currentBillingOrg : undefined,
+					};
+				} catch (err) {
+					logger.error("Error fetching billing orgs:", err);
+					set.status = 500;
+					return { error: "Internal server error" };
+				}
 			});
 	});

src/lib/server/endpoints/openai/endpointOai.ts

@@ -148,6 +148,10 @@ export async function endpointOai(
 					"ChatUI-Conversation-ID": conversationId?.toString() ?? "",
 					"X-use-cache": "false",
 					...(locals?.token ? { Authorization: `Bearer ${locals.token}` } : {}),
+					// Bill to organization if configured (HuggingChat only)
+					...(config.isHuggingChat && locals?.billingOrganization
+						? { "X-HF-Bill-To": locals.billingOrganization }
+						: {}),
 				},
 				signal: abortSignal,
 			});
@@ -218,6 +222,10 @@ export async function endpointOai(
 							"ChatUI-Conversation-ID": conversationId?.toString() ?? "",
 							"X-use-cache": "false",
 							...(locals?.token ? { Authorization: `Bearer ${locals.token}` } : {}),
+							// Bill to organization if configured (HuggingChat only)
+							...(config.isHuggingChat && locals?.billingOrganization
+								? { "X-HF-Bill-To": locals.billingOrganization }
+								: {}),
 						},
 						signal: abortSignal,
 					}
@@ -232,6 +240,10 @@ export async function endpointOai(
 							"ChatUI-Conversation-ID": conversationId?.toString() ?? "",
 							"X-use-cache": "false",
 							...(locals?.token ? { Authorization: `Bearer ${locals.token}` } : {}),
+							// Bill to organization if configured (HuggingChat only)
+							...(config.isHuggingChat && locals?.billingOrganization
+								? { "X-HF-Bill-To": locals.billingOrganization }
+								: {}),
 						},
 						signal: abortSignal,
 					}

src/lib/server/router/arch.ts

@@ -152,6 +152,10 @@ export async function archSelectRoute(
 	const headers: HeadersInit = {
 		Authorization: `Bearer ${getApiToken(locals)}`,
 		"Content-Type": "application/json",
+		// Bill to organization if configured (HuggingChat only)
+		...(config.isHuggingChat && locals?.billingOrganization
+			? { "X-HF-Bill-To": locals.billingOrganization }
+			: {}),
 	};
 	const body = {
 		model: archModel,

src/lib/server/textGeneration/mcp/runMcpFlow.ts

@@ -264,6 +264,12 @@ export async function* runMcpFlow({
 			apiKey: config.OPENAI_API_KEY || config.HF_TOKEN || "sk-",
 			baseURL: config.OPENAI_BASE_URL,
 			fetch: captureProviderFetch,
+			defaultHeaders: {
+				// Bill to organization if configured (HuggingChat only)
+				...(config.isHuggingChat && locals?.billingOrganization
+					? { "X-HF-Bill-To": locals.billingOrganization }
+					: {}),
+			},
 		});
 
 		const mmEnabled = (forceMultimodal ?? false) || targetModel.multimodal;

src/lib/stores/settings.ts

@@ -17,6 +17,7 @@ type SettingsStore = {
 	disableStream: boolean;
 	directPaste: boolean;
 	hidePromptExamples: Record<string, boolean>;
+	billingOrganization?: string;
 };
 
 type SettingsStoreWritable = Writable<SettingsStore> & {

src/lib/types/Settings.ts

@@ -35,6 +35,12 @@ export interface Settings extends Timestamps {
 
 	disableStream: boolean;
 	directPaste: boolean;
+
+	/**
+	 * Organization to bill inference requests to (HuggingChat only).
+	 * Stores the org's preferred_username. If empty/undefined, bills to personal account.
+	 */
+	billingOrganization?: string;
 }
 
 export type SettingsEditable = Omit<Settings, "welcomeModalSeenAt" | "createdAt" | "updatedAt">;

src/routes/conversation/[id]/+server.ts

@@ -517,6 +517,12 @@ export async function POST({ request, locals, params, getClientAddress }) {
 			const initialMessageContent = messageToWriteTo.content;
 
 			try {
+				// Fetch user settings once for all overrides and billing org
+				const userSettings = await collections.settings.findOne(authCondition(locals));
+
+				// Add billing organization to locals for the endpoint to use
+				locals.billingOrganization = userSettings?.billingOrganization;
+
 				const ctx: TextGenerationContext = {
 					model,
 					endpoint: await model.getEndpoint(),
@@ -527,15 +533,9 @@ export async function POST({ request, locals, params, getClientAddress }) {
 					ip: getClientAddress(),
 					username: locals.user?.username,
 					// Force-enable multimodal if user settings say so for this model
-					forceMultimodal: Boolean(
-						(await collections.settings.findOne(authCondition(locals)))?.multimodalOverrides?.[
-							model.id
-						]
-					),
+					forceMultimodal: Boolean(userSettings?.multimodalOverrides?.[model.id]),
 					// Force-enable tools if user settings say so for this model
-					forceTools: Boolean(
-						(await collections.settings.findOne(authCondition(locals)))?.toolsOverrides?.[model.id]
-					),
+					forceTools: Boolean(userSettings?.toolsOverrides?.[model.id]),
 					locals,
 					abortController: ctrl,
 				};

src/routes/login/callback/updateUser.spec.ts

@@ -99,7 +99,7 @@ describe("login", () => {
 		await updateUser({ userData, locals, cookies: cookiesMock, token });
 
 		// updateUser creates a new sessionId, so we need to use the updated value
-		const user = (await findUser(locals.sessionId)).user;
+		const user = (await findUser(locals.sessionId, undefined, new URL("http://localhost"))).user;
 
 		assert.exists(user);
 

src/routes/settings/(nav)/+server.ts

@@ -19,6 +19,7 @@ export async function POST({ request, locals }) {
 			disableStream: z.boolean().default(false),
 			directPaste: z.boolean().default(false),
 			hidePromptExamples: z.record(z.boolean()).default({}),
+			billingOrganization: z.string().optional(),
 		})
 		.parse(body) satisfies SettingsEditable;
 

src/routes/settings/(nav)/application/+page.svelte

@@ -41,21 +41,57 @@
 
 	const client = useAPIClient();
 
-	let OPENAI_BASE_URL: string | null = $state(null);
+	let OPENAI_BASE_URL = $state<string | null>(null);
+
+	// Billing organization state
+	type BillingOrg = { sub: string; name: string; preferred_username: string };
+	let billingOrgs = $state<BillingOrg[]>([]);
+	let billingOrgsLoading = $state(false);
+	let billingOrgsError = $state<string | null>(null);
+
+	function getBillingOrganization() {
+		return $settings.billingOrganization ?? "";
+	}
+	function setBillingOrganization(v: string) {
+		settings.update((s) => ({ ...s, billingOrganization: v || undefined }));
+	}
+
 	onMount(async () => {
+		// Fetch debug config
 		try {
 			const cfg = await client.debug.config.get().then(handleResponse);
 			OPENAI_BASE_URL = (cfg as { OPENAI_BASE_URL?: string }).OPENAI_BASE_URL || null;
 		} catch (e) {
 			// ignore if debug endpoint is unavailable
 		}
+
+		// Fetch billing organizations (only for HuggingChat + logged in users)
+		if (publicConfig.isHuggingChat && page.data.user) {
+			billingOrgsLoading = true;
+			try {
+				const data = (await client.user["billing-orgs"].get().then(handleResponse)) as {
+					userCanPay: boolean;
+					organizations: BillingOrg[];
+					currentBillingOrg?: string;
+				};
+				billingOrgs = data.organizations ?? [];
+				// Update settings if current billing org was cleared by server
+				if (data.currentBillingOrg !== getBillingOrganization()) {
+					setBillingOrganization(data.currentBillingOrg ?? "");
+				}
+			} catch {
+				billingOrgsError = "Failed to load billing options";
+			} finally {
+				billingOrgsLoading = false;
+			}
+		}
 	});
 
-	let themePref: ThemePreference = $state(browser ? getThemePreference() : "system");
+	let themePref = $state<ThemePreference>(browser ? getThemePreference() : "system");
 
 	// Admin: model refresh UI state
-	let refreshing: boolean = $state(false);
-	let refreshMessage: string | null = $state(null);
+	let refreshing = $state(false);
+	let refreshMessage = $state<string | null>(null);
 </script>
 
 <div class="flex w-full flex-col gap-4">
@@ -222,7 +258,64 @@
 			</div>
 		</div>
 
-		<div class="mt-6 flex flex-col gap-2 text-[13px]">
+		<!-- Billing section (HuggingChat only) -->
+		{#if publicConfig.isHuggingChat && page.data.user}
+			<div
+				class="rounded-xl border border-gray-200 bg-white px-3 shadow-sm dark:border-gray-700 dark:bg-gray-800"
+			>
+				<div class="divide-y divide-gray-200 dark:divide-gray-700">
+					<!-- Bill usage to -->
+					<div class="flex items-start justify-between py-3">
+						<div>
+							<div class="text-[13px] font-medium text-gray-800 dark:text-gray-200">Billing</div>
+							<p class="text-[12px] text-gray-500 dark:text-gray-400">
+								Select between personal or organization billing (for eligible organizations).
+							</p>
+						</div>
+						<div class="flex items-center">
+							{#if billingOrgsLoading}
+								<span class="text-xs text-gray-500 dark:text-gray-400">Loading...</span>
+							{:else if billingOrgsError}
+								<span class="text-xs text-red-500">{billingOrgsError}</span>
+							{:else}
+								<select
+									class="rounded-md border border-gray-300 bg-white px-1 py-1 text-xs text-gray-800 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-200"
+									value={getBillingOrganization()}
+									onchange={(e) => setBillingOrganization(e.currentTarget.value)}
+								>
+									<option value="">Personal</option>
+									{#each billingOrgs as org}
+										<option value={org.preferred_username}>{org.name}</option>
+									{/each}
+								</select>
+							{/if}
+						</div>
+					</div>
+					<!-- Providers Usage -->
+					<div class="flex items-start justify-between py-3">
+						<div>
+							<div class="text-[13px] font-medium text-gray-800 dark:text-gray-200">
+								Providers Usage
+							</div>
+							<p class="text-[12px] text-gray-500 dark:text-gray-400">
+								See which providers you use and choose your preferred ones.
+							</p>
+						</div>
+						<a
+							href={getBillingOrganization()
+								? `https://huggingface.co/organizations/${getBillingOrganization()}/settings/inference-providers/overview`
+								: "https://huggingface.co/settings/inference-providers/settings"}
+							target="_blank"
+							class="whitespace-nowrap rounded-md border border-gray-300 bg-white px-2.5 py-1 text-xs font-medium text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-200 dark:hover:bg-gray-600"
+						>
+							View Usage
+						</a>
+					</div>
+				</div>
+			</div>
+		{/if}
+
+		<div class="mt-6 flex flex-col gap-2 self-start text-[13px]">
 			{#if publicConfig.isHuggingChat}
 				<a
 					href="https://github.com/huggingface/chat-ui"
@@ -230,12 +323,6 @@
 					class="flex items-center underline decoration-gray-300 underline-offset-2 hover:decoration-gray-700 dark:decoration-gray-700 dark:hover:decoration-gray-400"
 					><CarbonLogoGithub class="mr-1.5 shrink-0 text-sm " /> Github repository</a
 				>
-				<a
-					href="https://huggingface.co/settings/inference-providers/settings"
-					target="_blank"
-					class="flex items-center underline decoration-gray-300 underline-offset-2 hover:decoration-gray-700 dark:decoration-gray-700 dark:hover:decoration-gray-400"
-					><CarbonArrowUpRight class="mr-1.5 shrink-0 text-sm " /> Providers settings</a
-				>
 				<a
 					href="https://huggingface.co/spaces/huggingchat/chat-ui/discussions/764"
 					target="_blank"