Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(billing): opt individual organizations into ClickHouse Billing (#18742)

Steffen Reuther5cb0a3d37172
diff --git a/.env.dev.example b/.env.dev.example
index 09af7f157f..134890d95e 100644
--- a/.env.dev.example
+++ b/.env.dev.example
@@ -396,6 +396,9 @@ CLICKHOUSE_ENABLE_SKIP_INDEXES_ON_DATA_READ=auto
# ClickHouse Billing (CHB) integration (Langfuse Cloud only). First-time
# upgrades on/after this UTC date (YYYY-MM-DD) route to CHB; unset = off.
# LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE=
+# Comma-separated organization ids whose first-time upgrade routes to CHB
+# regardless of the cutoff (single-org rollout testing).
+# LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS=
# Bearer secret for GET /api/billing/metrics; unset = endpoint disabled.
# CLICKHOUSE_BILLING_METRICS_API_KEY=
# CHB's EventBridge bus for project lifecycle events, authenticated by IAM from
diff --git a/.env.prod.example b/.env.prod.example
index 0dcb934a71..aec0121cf6 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -538,6 +538,9 @@ LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG=true
# ClickHouse Billing (CHB) integration (Langfuse Cloud only). First-time
# upgrades on/after this UTC date (YYYY-MM-DD) route to CHB; unset = off.
# LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE=
+# Comma-separated organization ids whose first-time upgrade routes to CHB
+# regardless of the cutoff (single-org rollout testing).
+# LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS=
# Bearer secret for GET /api/billing/metrics; unset = endpoint disabled.
# CLICKHOUSE_BILLING_METRICS_API_KEY=
# CHB's EventBridge bus for project lifecycle events, authenticated by IAM from
diff --git a/packages/shared/src/interfaces/billingProvider.test.ts b/packages/shared/src/interfaces/billingProvider.test.ts
index 92a5157de7..bd10b1cf5d 100644
--- a/packages/shared/src/interfaces/billingProvider.test.ts
+++ b/packages/shared/src/interfaces/billingProvider.test.ts
@@ -4,8 +4,10 @@ import { getBillingProvider, hasPaidBillingState } from "./billingProvider";
import { CloudConfigSchema } from "./cloudConfigSchema";
const CHB_ORG_ID = "0d5e6f7a-1b2c-4d3e-8f9a-0b1c2d3e4f5a";
+const ORG_ID = "org-1";
const orgWith = (cloudConfig: unknown) => ({
+ id: ORG_ID,
cloudConfig:
cloudConfig === null ? null : CloudConfigSchema.parse(cloudConfig),
});
@@ -80,6 +82,28 @@ describe("getBillingProvider", () => {
).toBe("stripe");
});
});
+
+ describe("opted-in orgs resolve to clickhouse without a cutoff", () => {
+ it("a never-billed org on the opt-in list resolves to clickhouse", () => {
+ expect(getBillingProvider(orgWith({}), { optInOrgIds: [ORG_ID] })).toBe(
+ "clickhouse",
+ );
+ });
+
+ it("an org missing from the opt-in list stays on stripe", () => {
+ expect(
+ getBillingProvider(orgWith({}), { optInOrgIds: ["org-other"] }),
+ ).toBe("stripe");
+ });
+
+ it("the opt-in does not move an org with Stripe state", () => {
+ expect(
+ getBillingProvider(orgWith({ stripe: { customerId: "cus_123" } }), {
+ optInOrgIds: [ORG_ID],
+ }),
+ ).toBe("stripe");
+ });
+ });
});
describe("hasPaidBillingState", () => {
diff --git a/packages/shared/src/interfaces/billingProvider.ts b/packages/shared/src/interfaces/billingProvider.ts
index c0ef1fec4b..b2e5b31ae1 100644
--- a/packages/shared/src/interfaces/billingProvider.ts
+++ b/packages/shared/src/interfaces/billingProvider.ts
@@ -12,24 +12,28 @@ type OrgWithCloudConfig = {
* Decision order:
* 1. Explicit CHB state always wins — the org is already on CHB. Sticky from
* the first checkout (which persists `clickhouse.organizationId`), so
- * later cutoff changes cannot strand an org mid-flow.
+ * later cutoff or opt-in changes cannot strand an org mid-flow.
* 2. Any existing Stripe billing state pins the org to Stripe (legacy). An
* existing billed customer can never flip providers via config.
- * 3. Otherwise the org has never been billed: the cutoff decides at upgrade
- * time — first checkouts on/after the cutoff go to CHB, regardless of when
- * the org was created. Until a checkout writes CHB state, resolving to
- * "clickhouse" has no side effects.
+ * 3. Otherwise the org has never been billed: an org on the opt-in list goes
+ * to CHB, independent of the cutoff, so a single org can run the CHB flow
+ * end to end before the global rollout.
+ * 4. For every other never-billed org the cutoff decides at upgrade time —
+ * first checkouts on/after the cutoff go to CHB, regardless of when the org
+ * was created. Until a checkout writes CHB state, resolving to "clickhouse"
+ * has no side effects.
*
- * The cutoff is injected rather than read from the environment: this module is
- * exported from the client-safe barrel, so it must not reach for the server env
- * schema. Each app passes the value from its own validated env.
+ * The cutoff and opt-in list are injected rather than read from the
+ * environment: this module is exported from the client-safe barrel, so it must
+ * not reach for the server env schema. Each app passes the values from its own
+ * validated env.
*
- * Absent cutoff ⇒ zero behavior change: nothing resolves to "clickhouse"
- * unless it already carries a `clickhouse` block.
+ * Absent cutoff and opt-in list ⇒ zero behavior change: nothing resolves to
+ * "clickhouse" unless it already carries a `clickhouse` block.
*/
export function getBillingProvider(
- org: OrgWithCloudConfig,
- opts?: { cutoff?: Date | null; now?: Date },
+ org: OrgWithCloudConfig & { id: string },
+ opts?: { cutoff?: Date | null; optInOrgIds?: string[]; now?: Date },
): BillingProvider {
if (org.cloudConfig?.clickhouse?.organizationId) return "clickhouse";
if (
@@ -37,6 +41,7 @@ export function getBillingProvider(
org.cloudConfig?.stripe?.activeSubscriptionId
)
return "stripe";
+ if (opts?.optInOrgIds?.includes(org.id)) return "clickhouse";
const cutoff = opts?.cutoff;
if (cutoff && (opts?.now ?? new Date()).getTime() >= cutoff.getTime())
return "clickhouse";
diff --git a/web/src/__tests__/server/unit/resolveBillingService.servertest.ts b/web/src/__tests__/server/unit/resolveBillingService.servertest.ts
index 96be74688f..fda77b7db7 100644
--- a/web/src/__tests__/server/unit/resolveBillingService.servertest.ts
+++ b/web/src/__tests__/server/unit/resolveBillingService.servertest.ts
@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
env: {
LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE: null as Date | null,
+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: [] as string[],
},
getChbApiClient: vi.fn(),
createBillingServiceFromContext: vi.fn(),
@@ -41,6 +42,7 @@ describe("resolveBillingService", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE = null;
+ mocks.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS = [];
mocks.createBillingServiceFromContext.mockReturnValue(STRIPE_SERVICE);
mocks.getChbApiClient.mockReturnValue({ client: true });
mocks.findOrg.mockResolvedValue({
@@ -98,6 +100,19 @@ describe("resolveBillingService", () => {
expect(billingProvider).toBe("clickhouse");
});
+ it("routes an opted-in never-billed org to CHB without a cutoff", async () => {
+ // Same plumbing guard as the cutoff: the opt-in list is injected too.
+ mocks.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS = [ORG_ID];
+
+ const { billingProvider, service } = await resolveBillingService(
+ ctxWithOrg({}),
+ ORG_ID,
+ );
+
+ expect(billingProvider).toBe("clickhouse");
+ expect(service).toBeInstanceOf(ChbBillingService);
+ });
+
it("fails closed to Stripe when the cutoff is set but the CHB env is incomplete", async () => {
mocks.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE = new Date(
"2020-01-01T00:00:00Z",
diff --git a/web/src/ee/features/billing/server/resolveBillingService.ts b/web/src/ee/features/billing/server/resolveBillingService.ts
index 55215403f2..71a5fcb67e 100644
--- a/web/src/ee/features/billing/server/resolveBillingService.ts
+++ b/web/src/ee/features/billing/server/resolveBillingService.ts
@@ -26,10 +26,10 @@ export type CloudBillingService =
* `cloudBillingRouter` procedures keep their names, inputs, and output
* shapes, so the tRPC contract does not change.
*
- * Fail-closed guard: when the CHB cutoff is set but the CHB REST env is
- * incomplete, cutoff-routed orgs (no CHB state yet) fall back to Stripe —
- * never a half-configured CHB flow. Orgs already carrying CHB state cannot be
- * served by Stripe and error instead.
+ * Fail-closed guard: when the CHB cutoff or opt-in list is set but the CHB
+ * REST env is incomplete, orgs routed by them (no CHB state yet) fall back to
+ * Stripe — never a half-configured CHB flow. Orgs already carrying CHB state
+ * cannot be served by Stripe and error instead.
*
* This dispatch is also the structural interlock that keeps Stripe checkout
* unreachable for any org holding a `cloudConfig.clickhouse` block: such
@@ -52,11 +52,13 @@ export const resolveBillingService = async (
});
}
const parsedOrg = parseDbOrg(org);
- // The cutoff is injected rather than read inside the resolver: the shared
- // module is exported from the client-safe barrel, so web passes the value from
- // its own validated env schema.
- const cutoff = env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE;
- const billingProvider = getBillingProvider(parsedOrg, { cutoff });
+ // The cutoff and opt-in list are injected rather than read inside the
+ // resolver: the shared module is exported from the client-safe barrel, so web
+ // passes the values from its own validated env schema.
+ const billingProvider = getBillingProvider(parsedOrg, {
+ cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,
+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,
+ });
if (billingProvider === "clickhouse") {
// Shared process-wide, so every billing request reuses one Auth0 token
@@ -73,12 +75,10 @@ export const resolveBillingService = async (
message: "ClickHouse Billing is not configured on this deployment",
});
}
- // Cutoff-routed org without CHB state: fail closed to Stripe
- if (cutoff) {
- logger.error(
- "resolveBillingService: LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE is set but the CHB REST env is incomplete — treating the cutoff as unset (fail closed to Stripe)",
- );
- }
+ // Cutoff- or opt-in-routed org without CHB state: fail closed to Stripe
+ logger.error(
+ `resolveBillingService: org ${orgId} routes to CHB by cutoff or opt-in but the CHB REST env is incomplete — falling back to Stripe`,
+ );
return {
billingProvider: "stripe",
service: createBillingServiceFromContext(ctx),
diff --git a/web/src/env.mjs b/web/src/env.mjs
index 2c93097310..2ed8dbc6c0 100644
--- a/web/src/env.mjs
+++ b/web/src/env.mjs
@@ -469,6 +469,19 @@ export const env = createEnv({
.date()
.optional()
.transform((date) => (date ? new Date(date) : null)),
+ // Comma-separated Langfuse organization ids whose first-time upgrade routes
+ // to CHB regardless of the cutoff, for testing the CHB flow on a single org
+ // before the global rollout. Orgs already billed by Stripe stay on Stripe.
+ // Keep in sync with worker/src/env.ts.
+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: z
+ .string()
+ .default("")
+ .transform((value) =>
+ value
+ .split(",")
+ .map((id) => id.trim())
+ .filter(Boolean),
+ ),
// Bearer secret CHB's metering pipeline presents to GET /api/billing/metrics.
// Unset disables the endpoint (it 500s) rather than leaving it open.
CLICKHOUSE_BILLING_METRICS_API_KEY: z.string().optional(),
@@ -1146,6 +1159,8 @@ export const env = createEnv({
STRIPE_WEBHOOK_SIGNING_SECRET: process.env.STRIPE_WEBHOOK_SIGNING_SECRET,
LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE:
process.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,
+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS:
+ process.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,
CLICKHOUSE_BILLING_METRICS_API_KEY:
process.env.CLICKHOUSE_BILLING_METRICS_API_KEY,
CLICKHOUSE_BILLING_EVENT_BUS_ARN:
diff --git a/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts b/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts
index 89a406fb47..27354c8e17 100644
--- a/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts
+++ b/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts
@@ -285,6 +285,7 @@ export const handleCloudSpendAlertJob = async (job: Job<{ orgId: string }>) => {
// unknown to CHB, so this is a hard fork rather than a fallback chain.
const billingProvider = getBillingProvider(org, {
cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,
+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,
});
try {
diff --git a/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts b/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts
index 2b7a282ae0..9f0b8cceb1 100644
--- a/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts
+++ b/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts
@@ -236,6 +236,7 @@ export const handleCloudUsageMeteringJob = async (job: Job) => {
if (
getBillingProvider(org, {
cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,
+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,
}) !== "stripe"
) {
traceException(
diff --git a/worker/src/env.ts b/worker/src/env.ts
index b4965cf315..e2dc1fb014 100644
--- a/worker/src/env.ts
+++ b/worker/src/env.ts
@@ -43,6 +43,17 @@ const EnvSchema = z.object({
.date()
.optional()
.transform((date) => (date ? new Date(date) : null)),
+ // Comma-separated Langfuse organization ids routed to CHB regardless of the
+ // cutoff; keep in sync with web/src/env.mjs.
+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: z
+ .string()
+ .default("")
+ .transform((value) =>
+ value
+ .split(",")
+ .map((id) => id.trim())
+ .filter(Boolean),
+ ),
// CHB REST credentials, mirroring web/src/env.mjs. The worker needs them for
// one read: the spend-alert job asks for the open period's accrued usage.