feat(billing): dollar usage surfaces off the org's billing numbers

codeUsageMeter picks what the meter shows: billing's org-level dollars
(ai_credits.used_usd/limit_usd, posthog#71404) when present — for both
tiers — else the free tier's per-user valve bucket, else nothing. The
titlebar becomes "Usage: $12.40" with an "of $X used" hover card and shows
for subscribed orgs too; the plans page meter reads "used of included/
limit" in dollars. Dollars are org-level truth — the valve fallback stays
because null numbers are a permanent state (an org before its first
billing sync), not just deploy lag. Upgrade-prompt analytics now fire only
for free-tier orgs.

Generated-By: PostHog Code
Task-Id: 1039ea23-9930-44e2-9888-b05cf8b129ec

Author: adboio

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

@@ -1,7 +1,9 @@
 import { describe, expect, it } from "vitest";
 import type { UsageOutput } from "../usage/schemas";
 import {
+  codeUsageMeter,
   formatResetTime,
+  formatUsdAmount,
   isCodeUsageFreeTier,
   isUsageExceeded,
 } from "./usageDisplay";
@@ -75,6 +77,74 @@ describe("isCodeUsageFreeTier", () => {
   });
 });
 
+describe("codeUsageMeter", () => {
+  it("prefers billing's org dollars when both numbers are present", () => {
+    const meter = codeUsageMeter({
+      ...makeUsage(),
+      code_usage_subscribed: true,
+      ai_credits: { exhausted: false, used_usd: 12.4, limit_usd: 50 },
+      billing_period_end: "2026-06-01T00:00:00.000Z",
+    });
+    expect(meter).toEqual({
+      kind: "dollars",
+      usedUsd: 12.4,
+      limitUsd: 50,
+      percent: 25,
+      exceeded: false,
+      resetAt: "2026-06-01T00:00:00.000Z",
+    });
+  });
+
+  it("marks the dollars meter exceeded from the org bucket and falls back to the sustained reset", () => {
+    const meter = codeUsageMeter({
+      ...makeUsage(),
+      code_usage_subscribed: false,
+      ai_credits: { exhausted: true, used_usd: 20, limit_usd: 20 },
+    });
+    expect(meter).toMatchObject({
+      kind: "dollars",
+      percent: 100,
+      exceeded: true,
+      resetAt: "2026-05-01T13:00:00.000Z",
+    });
+  });
+
+  it.each([
+    ["missing numbers", { exhausted: false }],
+    ["null numbers", { exhausted: false, used_usd: null, limit_usd: null }],
+    ["a zero limit", { exhausted: false, used_usd: 0, limit_usd: 0 }],
+  ])("falls back to the free-tier valve bucket with %s", (_name, aiCredits) => {
+    const usage: UsageOutput = {
+      ...makeUsage(),
+      code_usage_subscribed: false,
+      ai_credits: aiCredits,
+    };
+    expect(codeUsageMeter(usage)).toEqual({
+      kind: "bucket",
+      bucket: usage.sustained,
+    });
+  });
+
+  it("hides the meter for a subscribed or unknown org without dollars", () => {
+    expect(
+      codeUsageMeter({ ...makeUsage(), code_usage_subscribed: true }),
+    ).toEqual({ kind: "hidden" });
+    expect(codeUsageMeter(makeUsage())).toEqual({ kind: "hidden" });
+    expect(codeUsageMeter(null)).toEqual({ kind: "hidden" });
+  });
+});
+
+describe("formatUsdAmount", () => {
+  it.each([
+    [50, "$50"],
+    [12.4, "$12.40"],
+    [0.5, "$0.50"],
+    [0, "$0"],
+  ])("formats %s as %s", (amount, expected) => {
+    expect(formatUsdAmount(amount)).toBe(expected);
+  });
+});
+
 describe("formatResetTime", () => {
   const NOW = Date.parse("2026-05-01T12:00:00.000Z");
   const isoAt = (msFromNow: number) => new Date(NOW + msFromNow).toISOString();

packages/core/src/billing/usageDisplay.ts

@@ -1,4 +1,4 @@
-import type { UsageOutput } from "../usage/schemas";
+import type { UsageBucket, UsageOutput } from "../usage/schemas";
 
 /** Confirmed free tier only — an absent `code_usage_subscribed` is unknown, never free. */
 export function isCodeUsageFreeTier(
@@ -7,6 +7,50 @@ export function isCodeUsageFreeTier(
   return usage?.code_usage_subscribed === false;
 }
 
+export type CodeUsageMeter =
+  | {
+      kind: "dollars";
+      usedUsd: number;
+      limitUsd: number;
+      percent: number;
+      exceeded: boolean;
+      resetAt: string;
+    }
+  | { kind: "bucket"; bucket: UsageBucket }
+  | { kind: "hidden" };
+
+/**
+ * What the usage meter should show. Billing's org-level dollars win when
+ * present; a free-tier org without them falls back to its per-user valve
+ * bucket; anything else shows nothing — per-user valve percentages are
+ * meaningless for a subscribed org, and unknown must not render as free.
+ */
+export function codeUsageMeter(
+  usage: UsageOutput | null | undefined,
+): CodeUsageMeter {
+  if (!usage) return { kind: "hidden" };
+  const usedUsd = usage.ai_credits?.used_usd;
+  const limitUsd = usage.ai_credits?.limit_usd;
+  if (usedUsd != null && limitUsd != null && limitUsd > 0) {
+    return {
+      kind: "dollars",
+      usedUsd,
+      limitUsd,
+      percent: Math.min(100, Math.round((usedUsd / limitUsd) * 100)),
+      exceeded: usage.ai_credits?.exhausted === true,
+      resetAt: usage.billing_period_end ?? usage.sustained.reset_at,
+    };
+  }
+  if (isCodeUsageFreeTier(usage)) {
+    return { kind: "bucket", bucket: usage.sustained };
+  }
+  return { kind: "hidden" };
+}
+
+export function formatUsdAmount(amount: number): string {
+  return Number.isInteger(amount) ? `$${amount}` : `$${amount.toFixed(2)}`;
+}
+
 export function isUsageExceeded(usage: UsageOutput): boolean {
   return (
     usage.is_rate_limited || usage.sustained.exceeded || usage.burst.exceeded

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

@@ -1,4 +1,5 @@
 import { ArrowSquareOut, CreditCard } from "@phosphor-icons/react";
+import { formatUsdAmount } from "@posthog/core/billing/usageDisplay";
 import { ANALYTICS_EVENTS } from "@posthog/shared/analytics-events";
 import { Button, Dialog, Flex, Text } from "@radix-ui/themes";
 import { useEffect } from "react";
@@ -85,9 +86,7 @@ export function UsageBillingAnnouncementModal() {
               {limitUsd != null ? (
                 <>
                   • Your organization's spend limit is{" "}
-                  <Text weight="medium">
-                    {`$${Number.isInteger(limitUsd) ? limitUsd : limitUsd.toFixed(2)}/month`}
-                  </Text>{" "}
+                  <Text weight="medium">{`${formatUsdAmount(limitUsd)}/month`}</Text>{" "}
                   — adjust it any time in billing settings.
                 </>
               ) : (

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

@@ -1,7 +1,7 @@
 import { Circle } from "@phosphor-icons/react";
 import {
   formatResetTime,
-  isUsageExceeded,
+  formatUsdAmount,
 } from "@posthog/core/billing/usageDisplay";
 import {
   Button,
@@ -23,19 +23,19 @@ import {
   openSettings,
   prepareSettingsPage,
 } from "../settings/hooks/useOpenSettings";
-import { useFreeUsage } from "./useFreeUsage";
+import { useUsageMeter } from "./useUsageMeter";
 
 // Title-bar usage entry point (replaces the old sidebar usage bar): a compact
-// "Usage: N%" button whose hover card carries the full plan card — plan name,
-// progress bar, reset time, and the Upgrade action. Built on quill's Popover
+// usage button whose hover card carries the full plan card — plan name,
+// progress bar, reset time, and the plan action. Built on quill's Popover
 // with `openOnHover` on the trigger, so it behaves as a hover card (Base UI
-// keeps it open while the pointer travels into the card to click Upgrade).
+// keeps it open while the pointer travels into the card to click the action).
 // The card body styles with quill tokens (foreground/muted-foreground/primary,
 // quill Progress) — radix scale classes don't resolve inside the data-quill
 // popover portal.
 export function UsageButton() {
   const billingEnabled = useFeatureFlag(BILLING_FLAG);
-  const { usage, isLoading } = useFreeUsage(billingEnabled);
+  const { meter, freeTier, blocked, isLoading } = useUsageMeter(billingEnabled);
   // Controlled so the trigger click can close the card before navigating to
   // settings — uncontrolled, the same click would also toggle the popover open
   // over the settings view. Hover open/close still flows through onOpenChange.
@@ -45,7 +45,7 @@ export function UsageButton() {
 
   // Same-size placeholder while usage loads, so the button doesn't pop in and
   // shift the PostHog Web button after boot.
-  if (!usage) {
+  if (meter.kind === "hidden") {
     if (!isLoading) return null;
     return (
       <Button variant="outline" size="sm" disabled aria-hidden>
@@ -54,18 +54,27 @@ export function UsageButton() {
     );
   }
 
-  const exceeded = isUsageExceeded(usage);
-  const dominant =
-    usage.sustained.used_percent >= usage.burst.used_percent
-      ? usage.sustained
-      : usage.burst;
-  const usagePercent = Math.min(Math.round(dominant.used_percent), 100);
-  const resetLabel = formatResetTime(dominant.reset_at);
+  const percent =
+    meter.kind === "dollars"
+      ? meter.percent
+      : Math.min(Math.round(meter.bucket.used_percent), 100);
+  const buttonLabel = blocked
+    ? "Usage: limit reached"
+    : meter.kind === "dollars"
+      ? `Usage: ${formatUsdAmount(meter.usedUsd)}`
+      : `Usage: ${percent}%`;
+  const amountLabel =
+    meter.kind === "dollars"
+      ? `${formatUsdAmount(meter.usedUsd)} of ${formatUsdAmount(meter.limitUsd)} used`
+      : `${percent}% used`;
+  const resetLabel = formatResetTime(
+    meter.kind === "dollars" ? meter.resetAt : meter.bucket.reset_at,
+  );
 
+  // Upgrade-prompt analytics only apply to free-tier orgs — a subscribed
+  // org's meter is not an upgrade prompt.
   const handleOpenChange = (nextOpen: boolean) => {
-    // The hover card has real impressions now (the old sidebar bar was
-    // always-visible); count each open as a shown upgrade prompt.
-    if (nextOpen && !open) {
+    if (nextOpen && !open && freeTier) {
       track(ANALYTICS_EVENTS.UPGRADE_PROMPT_SHOWN, {
         surface: "titlebar_card",
       });
@@ -74,7 +83,9 @@ export function UsageButton() {
   };
 
   const handleOpenPlan = (surface: UpgradePromptClickedSurface) => {
-    track(ANALYTICS_EVENTS.UPGRADE_PROMPT_CLICKED, { surface });
+    if (freeTier) {
+      track(ANALYTICS_EVENTS.UPGRADE_PROMPT_CLICKED, { surface });
+    }
     setOpen(false);
     openSettings("plan-usage");
   };
@@ -84,7 +95,9 @@ export function UsageButton() {
   // openSettings would have done — tracking, closing the card, and resetting
   // the settings-page store so no stale context/one-shot action leaks in.
   const handleTriggerClick = () => {
-    track(ANALYTICS_EVENTS.UPGRADE_PROMPT_CLICKED, { surface: "titlebar" });
+    if (freeTier) {
+      track(ANALYTICS_EVENTS.UPGRADE_PROMPT_CLICKED, { surface: "titlebar" });
+    }
     setOpen(false);
     prepareSettingsPage();
   };
@@ -107,7 +120,7 @@ export function UsageButton() {
               />
             }
           >
-            {exceeded ? "Usage: limit reached" : `Usage: ${usagePercent}%`}
+            {buttonLabel}
           </Button>
         }
       />
@@ -121,14 +134,14 @@ export function UsageButton() {
       >
         <div className="flex items-center justify-between">
           <span className="font-medium text-foreground text-xs">
-            Free tier
+            {freeTier ? "Free tier" : "Usage-based billing"}
             <Circle
               size={4}
               weight="fill"
               className="mx-1.5 inline text-muted-foreground"
             />
             <span className="font-normal text-muted-foreground">
-              {exceeded ? "Limit reached" : `${usagePercent}% used`}
+              {blocked ? "Limit reached" : amountLabel}
             </span>
           </span>
           <Button
@@ -137,12 +150,12 @@ export function UsageButton() {
             className="h-auto p-0"
             onClick={() => handleOpenPlan("titlebar_card")}
           >
-            Unlock more
+            {freeTier ? "Unlock more" : "View usage"}
           </Button>
         </div>
         <Progress
-          value={usagePercent}
-          variant={exceeded ? "destructive" : "default"}
+          value={percent}
+          variant={blocked ? "destructive" : "default"}
         />
         <div className="font-normal text-[11px] text-muted-foreground">
           {resetLabel}

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

@@ -1,16 +1,20 @@
-import { formatResetTime } from "@posthog/core/billing/usageDisplay";
-import type { UsageBucket } from "@posthog/core/usage/schemas";
 import { Flex, Progress, Text } from "@radix-ui/themes";
 
 interface UsageMeterProps {
   label: string;
-  bucket: UsageBucket;
+  percent: number;
+  valueLabel: string;
+  detail: string;
   color?: "red";
 }
 
-export function UsageMeter({ label, bucket, color }: UsageMeterProps) {
-  const percentage = bucket.used_percent;
-
+export function UsageMeter({
+  label,
+  percent,
+  valueLabel,
+  detail,
+  color,
+}: UsageMeterProps) {
   const borderColor = color === "red" ? "var(--red-7)" : "var(--gray-5)";
 
   return (
@@ -25,16 +29,14 @@ export function UsageMeter({ label, bucket, color }: UsageMeterProps) {
     >
       <Flex align="center" justify="between">
         <Text className="font-medium text-sm">{label}</Text>
-        <Text className="font-medium text-sm">{percentage.toFixed(2)}%</Text>
+        <Text className="font-medium text-sm">{valueLabel}</Text>
       </Flex>
       <Progress
-        value={percentage}
+        value={percent}
         size="2"
         color={color === "red" ? "red" : undefined}
       />
-      <Text className="text-(--gray-9) text-[13px]">
-        {`${bucket.exceeded ? "Limit exceeded. " : ""}${formatResetTime(bucket.reset_at)}`}
-      </Text>
+      <Text className="text-(--gray-9) text-[13px]">{detail}</Text>
     </Flex>
   );
 }