refactor(billing): rename subscription bit to code_usage_subscribed

Matches the gateway field rename: the bit is the org's subscription status (payment method on file), and "billed" next to is_pro read ambiguously. Mechanical rename across the schema, gateway service, limit-content derivation, and billing UI; is_pro semantics untouched.

Generated-By: PostHog Code
Task-Id: bfbcd747-a365-429f-a5dc-622e2c2f7edf

Author: adboio

packages/core/src/billing/usageDisplay.ts

@@ -10,14 +10,15 @@ export function isUsageExceeded(usage: UsageOutput): boolean {
 }
 
 /**
- * The org is confirmed on the free tier (not billed for Code usage). False
- * when billed OR when the state is unknown — `code_usage_billed` is absent on
- * gateways predating the field, and absence must never read as free.
+ * The org is confirmed on the free tier (not subscribed to Code usage
+ * billing). False when subscribed OR when the state is unknown —
+ * `code_usage_subscribed` is absent on gateways predating the field, and
+ * absence must never read as free.
  */
-export function isCodeUsageUnbilled(
-  usage: Pick<UsageOutput, "code_usage_billed"> | null | undefined,
+export function isCodeUsageUnsubscribed(
+  usage: Pick<UsageOutput, "code_usage_subscribed"> | null | undefined,
 ): boolean {
-  return usage?.code_usage_billed === false;
+  return usage?.code_usage_subscribed === false;
 }
 
 export function formatResetTime(

packages/core/src/billing/usageLimitContent.test.ts

@@ -22,7 +22,7 @@ describe("usageBasedLimitContent", () => {
       cause: "model_gate",
       model: "Claude Opus 4.8",
       resetLabel: null,
-      billed: false,
+      subscribed: false,
     });
     expect(content.title).toBe("Unlock premium models");
     expect(content.description).toContain("Claude Opus 4.8 isn't");
@@ -34,26 +34,26 @@ describe("usageBasedLimitContent", () => {
       cause: "model_gate",
       model: null,
       resetLabel: null,
-      billed: undefined,
+      subscribed: undefined,
     });
     expect(content.description).toContain("This model isn't");
   });
 
   it.each([
-    // Confirmed-free org: allocation used up, the fix is adding a card.
+    // Confirmed-unsubscribed org: allocation used up, the fix is adding a card.
     [false, "Free usage used up", "Add payment method"],
-    // Billed org: the fix is raising the spend limit.
+    // Subscribed org: the fix is raising the spend limit.
     [true, "Organization usage limit reached", "Manage billing"],
-    // Unknown billed state must not read as free.
+    // Unknown subscription state must not read as free.
     [undefined, "Organization usage limit reached", "Manage billing"],
   ] as const)(
-    "org_limit with billed=%s -> %s / %s",
-    (billed, title, actionLabel) => {
+    "org_limit with subscribed=%s -> %s / %s",
+    (subscribed, title, actionLabel) => {
       const content = usageBasedLimitContent({
         cause: "org_limit",
         model: null,
         resetLabel: null,
-        billed,
+        subscribed,
       });
       expect(content.title).toBe(title);
       expect(content.actionLabel).toBe(actionLabel);
@@ -68,7 +68,7 @@ describe("usageBasedLimitContent", () => {
       cause,
       model: null,
       resetLabel: "Resets in 2h",
-      billed: false,
+      subscribed: false,
     });
     expect(content.title).toBe(title);
     expect(content.description).toContain("Resets in 2h");

packages/core/src/billing/usageLimitContent.ts

@@ -27,10 +27,10 @@ export function usageBasedLimitContent(args: {
   cause: GatewayLimitCause;
   model: string | null;
   resetLabel: string | null;
-  /** usage.code_usage_billed — absent means unknown, not free. */
-  billed: boolean | undefined;
+  /** usage.code_usage_subscribed — absent means unknown, not free. */
+  subscribed: boolean | undefined;
 }): UsageLimitContent {
-  const { cause, model, resetLabel, billed } = args;
+  const { cause, model, resetLabel, subscribed } = args;
 
   if (cause === "model_gate") {
     return {
@@ -42,7 +42,7 @@ export function usageBasedLimitContent(args: {
   }
 
   if (cause === "org_limit") {
-    if (billed === false) {
+    if (subscribed === false) {
       return {
         title: "Free usage used up",
         description:

packages/core/src/llm-gateway/llm-gateway.test.ts

@@ -202,14 +202,14 @@ describe("LlmGatewayService.prompt", () => {
     expect(retryBody.model).toBe("@cf/zai-org/glm-5.2");
   });
 
-  it("routes straight to the free-tier model once the org is known unbilled", async () => {
+  it("routes straight to the free-tier model once the org is known unsubscribed", async () => {
     const fetchMock = vi
       .fn()
       .mockResolvedValueOnce(createJsonResponse(MODEL_GATE_BODY, 403))
       .mockImplementation(async () => createJsonResponse(SUCCESS_BODY));
     const { service } = createService(fetchMock);
 
-    // First call learns "unbilled" from the gate's 403.
+    // First call learns "unsubscribed" from the gate's 403.
     await service.prompt([{ role: "user", content: "hi" }], {
       model: "claude-haiku-4-5",
     });
@@ -303,22 +303,22 @@ describe("LlmGatewayService.fetchUsage", () => {
       createJsonResponse({
         ...USAGE_BODY,
         ai_credits: { exhausted: true },
-        code_usage_billed: true,
+        code_usage_subscribed: true,
       }),
     );
     const { service } = createService(fetchMock);
 
     const usage = await service.fetchUsage();
 
     expect(usage.ai_credits?.exhausted).toBe(true);
-    expect(usage.code_usage_billed).toBe(true);
+    expect(usage.code_usage_subscribed).toBe(true);
   });
 
-  it("feeds code_usage_billed into helper model routing", async () => {
+  it("feeds code_usage_subscribed into helper model routing", async () => {
     const fetchMock = vi
       .fn()
       .mockResolvedValueOnce(
-        createJsonResponse({ ...USAGE_BODY, code_usage_billed: false }),
+        createJsonResponse({ ...USAGE_BODY, code_usage_subscribed: false }),
       )
       .mockResolvedValue(createJsonResponse(SUCCESS_BODY));
     const { service } = createService(fetchMock);

packages/core/src/llm-gateway/llm-gateway.ts

@@ -60,11 +60,11 @@ export class LlmGatewayService {
   private readonly endpoints: LlmGatewayEndpoints;
   private readonly log: LlmGatewayLogger;
 
-  // Last code_usage_billed seen from the gateway (usage fetches ride through
-  // this service, and the usage monitor refreshes on LLM activity, so this
-  // stays warm). null until the gateway has told us either way — old gateways
-  // omit the field entirely.
-  private lastKnownCodeUsageBilled: boolean | null = null;
+  // Last code_usage_subscribed seen from the gateway (usage fetches ride
+  // through this service, and the usage monitor refreshes on LLM activity, so
+  // this stays warm). null until the gateway has told us either way — old
+  // gateways omit the field entirely.
+  private lastKnownCodeUsageSubscribed: boolean | null = null;
 
   async prompt(
     messages: LlmMessage[],
@@ -89,7 +89,7 @@ export class LlmGatewayService {
     // free tier, route helpers to the free-tier model upfront instead of
     // burning a request on the model gate's 403.
     const model =
-      this.lastKnownCodeUsageBilled === false
+      this.lastKnownCodeUsageSubscribed === false
         ? FREE_TIER_GATEWAY_MODEL
         : requested;
     try {
@@ -100,10 +100,10 @@ export class LlmGatewayService {
         error.statusCode === 403 &&
         classifyGatewayLimitError(error.message) === "model_gate";
       if (!isModelGate || model === FREE_TIER_GATEWAY_MODEL) throw error;
-      // Backstop for a stale billed bit (org just lost billing): the gate
-      // itself is authoritative that the org isn't billed, so remember that
+      // Backstop for a stale subscription bit (org just unsubscribed): the gate
+      // itself is authoritative that the org isn't subscribed, so remember that
       // and degrade this call instead of failing it.
-      this.lastKnownCodeUsageBilled = false;
+      this.lastKnownCodeUsageSubscribed = false;
       this.log.warn("Model gated for free tier, retrying on free-tier model", {
         model,
         fallbackModel: FREE_TIER_GATEWAY_MODEL,
@@ -282,8 +282,8 @@ export class LlmGatewayService {
     }
 
     const usage = usageOutput.parse(await response.json());
-    if (usage.code_usage_billed !== undefined) {
-      this.lastKnownCodeUsageBilled = usage.code_usage_billed;
+    if (usage.code_usage_subscribed !== undefined) {
+      this.lastKnownCodeUsageSubscribed = usage.code_usage_subscribed;
     }
     return usage;
   }

packages/core/src/usage/schemas.ts

@@ -18,9 +18,10 @@ export const usageOutput = z.object({
   is_rate_limited: z.boolean(),
   // Seat-era plan bit; false for everyone once seats are retired.
   is_pro: z.boolean(),
-  // True when the org pays for Code usage (usage-based billing). Absent on
-  // gateways that predate the field — treat absence as unknown, not false.
-  code_usage_billed: z.boolean().optional(),
+  // True when the org is subscribed to Code usage billing (payment method
+  // on file). Absent on gateways that predate the field — treat absence as
+  // unknown, not false.
+  code_usage_subscribed: z.boolean().optional(),
   billing_period_end: z.string().datetime().nullable().optional(),
 });
 

packages/ui/src/features/billing/UsageLimitModal.tsx

@@ -36,7 +36,7 @@ export function UsageLimitModal() {
   const { isPro: seatIsPro } = useSeat();
   const usageBillingEnabled = useFeatureFlag(USAGE_BILLING_FLAG);
   const cloudRegion = useAuthStateValue((state) => state.cloudRegion);
-  // Whether the org pays for Code usage — picks the org_limit copy variant.
+  // The org's Code usage subscription — picks the org_limit copy variant.
   const { usage } = useUsage({ enabled: usageBillingEnabled && isOpen });
   const isPro = eventIsPro ?? seatIsPro;
 
@@ -60,7 +60,7 @@ export function UsageLimitModal() {
         cause: deriveUsageLimitCause(cause, bucket),
         model,
         resetLabel,
-        billed: usage?.code_usage_billed,
+        subscribed: usage?.code_usage_subscribed,
       })
     : seatEraLimitContent({ bucket, isPro, resetLabel });
 

packages/ui/src/features/billing/useFreeUsage.ts

@@ -1,4 +1,4 @@
-import { isCodeUsageUnbilled } from "@posthog/core/billing/usageDisplay";
+import { isCodeUsageUnsubscribed } from "@posthog/core/billing/usageDisplay";
 import type { UsageOutput } from "@posthog/core/usage/schemas";
 import { USAGE_BILLING_FLAG } from "@posthog/shared";
 import { useFeatureFlag } from "../feature-flags/useFeatureFlag";
@@ -17,16 +17,16 @@ export function useFreeUsage(billingEnabled: boolean): FreeUsageResult {
   const { seat, isPro } = useSeat();
   const seatLoaded = seat !== null;
   // Seat era: free-seat holders only. Usage era: seats are gone — fetch for
-  // everyone, then show only orgs the gateway confirms as unbilled (the free
+  // everyone, then show only orgs the gateway confirms unsubscribed (the free
   // tier's per-user allowance is the meaningful meter).
   const eligible = usageBillingEnabled
     ? billingEnabled
     : billingEnabled && seatLoaded && !isPro;
   const { usage, isLoading } = useUsage({ enabled: eligible });
 
   if (!eligible) return { usage: null, isLoading: false };
-  if (usageBillingEnabled && !isCodeUsageUnbilled(usage)) {
-    // Billed org (no per-user caps to meter) or billed state unknown: the
+  if (usageBillingEnabled && !isCodeUsageUnsubscribed(usage)) {
+    // Subscribed org (no per-user caps to meter) or unknown state: the
     // free-tier bar would be noise or wrong — render nothing.
     return { usage: null, isLoading: usage ? false : isLoading };
   }

packages/ui/src/features/settings/sections/PlanUsageSettings.tsx

@@ -5,7 +5,7 @@ import {
   WarningCircle,
 } from "@phosphor-icons/react";
 import {
-  isCodeUsageUnbilled,
+  isCodeUsageUnsubscribed,
   PRO_USAGE_MULTIPLIER,
 } from "@posthog/core/billing/usageDisplay";
 import type { UsageOutput } from "@posthog/core/usage/schemas";
@@ -528,9 +528,9 @@ function UsageBasedPlanUsage({
   billingUrl,
   onOpenBilling,
 }: UsageBasedPlanUsageProps) {
-  // Tri-state: unknown (absent field) must render as billed, never as free.
-  const unbilled = isCodeUsageUnbilled(usage);
-  const billed = usage?.code_usage_billed === true;
+  // Tri-state: unknown (absent field) must render as subscribed, never free.
+  const unsubscribed = isCodeUsageUnsubscribed(usage);
+  const subscribed = usage?.code_usage_subscribed === true;
   const orgLimitReached = usage?.ai_credits?.exhausted === true;
 
   return (
@@ -571,28 +571,30 @@ function UsageBasedPlanUsage({
         <Flex align="center" justify="between">
           <Flex direction="column" gap="1">
             <Text className="font-bold text-base">
-              {unbilled ? "Free tier" : "Usage-based billing"}
+              {unsubscribed ? "Free tier" : "Usage-based billing"}
             </Text>
             <Text className="text-(--gray-11) text-sm">
-              {unbilled
+              {unsubscribed
                 ? "Your organization's first $20 of usage each month is included, with access to open models. Add a payment method to unlock premium models — you only pay for what you use."
-                : "Your organization pays for PostHog Code usage at cost — no seats, no subscriptions. The first $20 each month is included."}
+                : "Your organization pays for PostHog Code usage at cost — no seats, no per-user plans. The first $20 each month is included."}
             </Text>
           </Flex>
-          {billed && (
+          {subscribed && (
             <Badge variant="soft" color="green" radius="full">
               Active
             </Badge>
           )}
         </Flex>
         <Button
           size="1"
-          variant={unbilled ? "solid" : "outline"}
+          variant={unsubscribed ? "solid" : "outline"}
           disabled={!billingUrl}
           onClick={onOpenBilling}
           className="self-start"
         >
-          {unbilled ? "Add payment method" : "Manage billing and spend limits"}
+          {unsubscribed
+            ? "Add payment method"
+            : "Manage billing and spend limits"}
           <ArrowSquareOut size={12} />
         </Button>
       </Flex>
@@ -608,7 +610,7 @@ function UsageBasedPlanUsage({
           >
             <Spinner size="2" />
           </Flex>
-        ) : unbilled && usage ? (
+        ) : unsubscribed && usage ? (
           <Flex direction="column" gap="3">
             <UsageMeter
               label="Monthly free usage"