fix(billing): explain the merged usage limit as included allowance + spend limit

adboio · adboio · commit 927acb0c7461 · 2026-07-16T09:59:23.000-04:00
A subscribed org's ai_credits.limit_usd arrives from the gateway as one
merged number: the $20 included monthly allowance plus the configured
spend limit. The plans-page meter and title-bar card rendered it raw, so
an org on the default limit saw a total matching nothing it configured,
and the billing announcement modal misquoted the merged number as the
org's spend limit.

Derive the breakdown in codeUsageMeter (via codeOrgSpendLimitUsd), spell
it out under both meters ("$20 included + $50 org spend limit"), notch
the plans-page bar where the included allowance ends, and quote the
recovered spend limit in the announcement modal.

Generated-By: PostHog Code
Task-Id: b24f71e2-3751-4a6b-b5d8-a24147c4c067
diff --git a/packages/core/src/billing/usageDisplay.test.ts b/packages/core/src/billing/usageDisplay.test.ts
@@ -1,8 +1,10 @@
 import { describe, expect, it } from "vitest";
 import type { UsageOutput } from "../usage/schemas";
 import {
+  codeOrgSpendLimitUsd,
   codeUsageMeter,
   formatResetTime,
+  formatUsageBreakdown,
   formatUsdAmount,
   isCodeUsageFreeTier,
   isUsageExceeded,
@@ -92,9 +94,32 @@ describe("codeUsageMeter", () => {
       percent: 25,
       exceeded: false,
       resetAt: "2026-06-01T00:00:00.000Z",
+      breakdown: { includedUsd: 20, spendLimitUsd: 30 },
     });
   });
 
+  it("splits a default-settings subscribed limit into $20 included + $50 spend limit", () => {
+    const meter = codeUsageMeter({
+      ...makeUsage(),
+      code_usage_subscribed: true,
+      ai_credits: { exhausted: false, used_usd: 5, limit_usd: 70 },
+    });
+    expect(meter).toMatchObject({
+      kind: "dollars",
+      limitUsd: 70,
+      breakdown: { includedUsd: 20, spendLimitUsd: 50 },
+    });
+  });
+
+  it("keeps a free org's dollars meter breakdown-free — its limit is just the allowance", () => {
+    const meter = codeUsageMeter({
+      ...makeUsage(),
+      code_usage_subscribed: false,
+      ai_credits: { exhausted: false, used_usd: 5, limit_usd: 20 },
+    });
+    expect(meter).toMatchObject({ kind: "dollars", breakdown: null });
+  });
+
   it("marks the dollars meter exceeded from the org bucket and falls back to the sustained reset", () => {
     const meter = codeUsageMeter({
       ...makeUsage(),
@@ -134,6 +159,59 @@ describe("codeUsageMeter", () => {
   });
 });
 
+describe("codeOrgSpendLimitUsd", () => {
+  const subscribedWithLimit = (limitUsd: number | null) => ({
+    code_usage_subscribed: true,
+    ai_credits: { exhausted: false, used_usd: 0, limit_usd: limitUsd },
+  });
+
+  it.each([
+    ["default settings", 70, 50],
+    ["custom limit", 120.5, 100.5],
+    ["a $0 spend limit is a real answer", 20, 0],
+  ])("recovers the configured limit with %s", (_name, limitUsd, expected) => {
+    expect(codeOrgSpendLimitUsd(subscribedWithLimit(limitUsd))).toBe(expected);
+  });
+
+  it("returns null when the merged limit is below the allowance", () => {
+    expect(codeOrgSpendLimitUsd(subscribedWithLimit(15))).toBeNull();
+  });
+
+  it("returns null without a limit number", () => {
+    expect(codeOrgSpendLimitUsd(subscribedWithLimit(null))).toBeNull();
+    expect(
+      codeOrgSpendLimitUsd({
+        code_usage_subscribed: true,
+        ai_credits: undefined,
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null for free, unknown, or missing orgs", () => {
+    expect(
+      codeOrgSpendLimitUsd({
+        code_usage_subscribed: false,
+        ai_credits: { exhausted: false, used_usd: 0, limit_usd: 20 },
+      }),
+    ).toBeNull();
+    expect(
+      codeOrgSpendLimitUsd({
+        code_usage_subscribed: undefined,
+        ai_credits: { exhausted: false, used_usd: 0, limit_usd: 70 },
+      }),
+    ).toBeNull();
+    expect(codeOrgSpendLimitUsd(null)).toBeNull();
+  });
+});
+
+describe("formatUsageBreakdown", () => {
+  it("phrases the merged limit as included + spend limit", () => {
+    expect(formatUsageBreakdown({ includedUsd: 20, spendLimitUsd: 50 })).toBe(
+      "$20 included + $50 org spend limit",
+    );
+  });
+});
+
 describe("formatUsdAmount", () => {
   it.each([
     [50, "$50"],
diff --git a/packages/core/src/billing/usageDisplay.ts b/packages/core/src/billing/usageDisplay.ts
@@ -1,12 +1,49 @@
 import type { UsageBucket, UsageOutput } from "../usage/schemas";
 
+/**
+ * The monthly usage allowance included for every org under Code usage
+ * billing — the "first $20 each month is included" from the billing product
+ * config. The gateway has no field for it: a subscribed org's
+ * `ai_credits.limit_usd` arrives as one merged number (allowance + configured
+ * spend limit), so display code peels the allowance back off with this
+ * constant. If billing ever changes the allowance or starts sending a
+ * breakdown, this constant (and the copy quoting $20) is the seam.
+ */
+export const CODE_INCLUDED_USAGE_USD = 20;
+
 /** Confirmed free tier only — an absent `code_usage_subscribed` is unknown, never free. */
 export function isCodeUsageFreeTier(
   usage: Pick<UsageOutput, "code_usage_subscribed"> | null | undefined,
 ): boolean {
   return usage?.code_usage_subscribed === false;
 }
 
+/**
+ * The spend limit the org actually configured in billing settings ($50 by
+ * default), recovered from the merged `limit_usd`. Null when it can't be
+ * recovered: unconfirmed/free orgs (their limit IS the allowance), missing
+ * numbers, or a merged limit below the allowance. Zero is a real answer — a
+ * subscribed org whose merged limit equals the allowance set its spend limit
+ * to $0.
+ */
+export function codeOrgSpendLimitUsd(
+  usage:
+    | Pick<UsageOutput, "code_usage_subscribed" | "ai_credits">
+    | null
+    | undefined,
+): number | null {
+  if (usage?.code_usage_subscribed !== true) return null;
+  const limitUsd = usage.ai_credits?.limit_usd;
+  if (limitUsd == null || limitUsd < CODE_INCLUDED_USAGE_USD) return null;
+  // Round away float dust — the wire amounts are already cent-rounded.
+  return Math.round((limitUsd - CODE_INCLUDED_USAGE_USD) * 100) / 100;
+}
+
+export interface CodeUsageBreakdown {
+  includedUsd: number;
+  spendLimitUsd: number;
+}
+
 export type CodeUsageMeter =
   | {
       kind: "dollars";
@@ -15,6 +52,10 @@ export type CodeUsageMeter =
       percent: number;
       exceeded: boolean;
       resetAt: string;
+      // How the merged limit decomposes for a subscribed org, so the meter
+      // can explain "$70" as $20 included + $50 spend limit. Null when the
+      // split is unknown (free tier, or a limit below the allowance).
+      breakdown: CodeUsageBreakdown | null;
     }
   | { kind: "bucket"; bucket: UsageBucket }
   | { kind: "hidden" };
@@ -32,13 +73,18 @@ export function codeUsageMeter(
   const usedUsd = usage.ai_credits?.used_usd;
   const limitUsd = usage.ai_credits?.limit_usd;
   if (usedUsd != null && limitUsd != null && limitUsd > 0) {
+    const spendLimitUsd = codeOrgSpendLimitUsd(usage);
     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,
+      breakdown:
+        spendLimitUsd != null
+          ? { includedUsd: CODE_INCLUDED_USAGE_USD, spendLimitUsd }
+          : null,
     };
   }
   if (isCodeUsageFreeTier(usage)) {
@@ -51,6 +97,11 @@ export function formatUsdAmount(amount: number): string {
   return Number.isInteger(amount) ? `$${amount}` : `$${amount.toFixed(2)}`;
 }
 
+/** One shared phrasing for the merged-limit explanation, e.g. "$20 included + $50 org spend limit". */
+export function formatUsageBreakdown(breakdown: CodeUsageBreakdown): string {
+  return `${formatUsdAmount(breakdown.includedUsd)} included + ${formatUsdAmount(breakdown.spendLimitUsd)} org spend limit`;
+}
+
 export function isUsageExceeded(usage: UsageOutput): boolean {
   return (
     usage.is_rate_limited || usage.sustained.exceeded || usage.burst.exceeded
diff --git a/packages/ui/src/features/billing/UsageBillingAnnouncementModal.tsx b/packages/ui/src/features/billing/UsageBillingAnnouncementModal.tsx
@@ -1,5 +1,8 @@
 import { ArrowSquareOut, CreditCard } from "@phosphor-icons/react";
-import { formatUsdAmount } from "@posthog/core/billing/usageDisplay";
+import {
+  codeOrgSpendLimitUsd,
+  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";
@@ -22,12 +25,11 @@ export function UsageBillingAnnouncementModal() {
   const cloudRegion = useAuthStateValue((state) => state.cloudRegion);
   const { usage } = useUsage({ enabled: isOpen });
 
-  // A free org's limit_usd is its included allocation (the first bullet's
-  // $20), not a spend limit — the org-specific line is for subscribed orgs.
-  const limitUsd =
-    usage?.code_usage_subscribed === true
-      ? (usage.ai_credits?.limit_usd ?? null)
-      : null;
+  // A subscribed org's limit_usd merges the included $20 with the configured
+  // spend limit — quote the recovered spend limit, the number the org set.
+  // Free orgs (whose limit_usd is just the first bullet's $20) get the
+  // default-limit line instead.
+  const spendLimitUsd = codeOrgSpendLimitUsd(usage);
 
   useEffect(() => {
     if (isOpen) {
@@ -83,10 +85,10 @@ export function UsageBillingAnnouncementModal() {
               • Premium models need a payment method; an open model stays free.
             </Text>
             <Text color="gray">
-              {limitUsd != null ? (
+              {spendLimitUsd != null ? (
                 <>
                   • Your organization's spend limit is{" "}
-                  <Text weight="medium">{`${formatUsdAmount(limitUsd)}/month`}</Text>{" "}
+                  <Text weight="medium">{`${formatUsdAmount(spendLimitUsd)}/month`}</Text>{" "}
                   — adjust it any time in billing settings.
                 </>
               ) : (
diff --git a/packages/ui/src/features/billing/UsageButton.tsx b/packages/ui/src/features/billing/UsageButton.tsx
@@ -1,6 +1,7 @@
 import { Circle } from "@phosphor-icons/react";
 import {
   formatResetTime,
+  formatUsageBreakdown,
   formatUsdAmount,
 } from "@posthog/core/billing/usageDisplay";
 import {
@@ -70,6 +71,13 @@ export function UsageButton() {
   const resetLabel = formatResetTime(
     meter.kind === "dollars" ? meter.resetAt : meter.bucket.reset_at,
   );
+  // The subscribed meter's limit is a merged number (included allowance +
+  // configured spend limit); without the split, "$70" matches nothing the
+  // user ever set.
+  const breakdownLabel =
+    meter.kind === "dollars" && meter.breakdown
+      ? formatUsageBreakdown(meter.breakdown)
+      : null;
 
   // Upgrade-prompt analytics only apply to free-tier orgs — a subscribed
   // org's meter is not an upgrade prompt.
@@ -158,7 +166,7 @@ export function UsageButton() {
           variant={blocked ? "destructive" : "default"}
         />
         <div className="font-normal text-[11px] text-muted-foreground">
-          {resetLabel}
+          {breakdownLabel ? `${breakdownLabel} · ${resetLabel}` : resetLabel}
         </div>
       </PopoverContent>
     </Popover>
diff --git a/packages/ui/src/features/billing/UsageMeter.stories.tsx b/packages/ui/src/features/billing/UsageMeter.stories.tsx
@@ -0,0 +1,61 @@
+import { UsageMeter } from "@posthog/ui/features/billing/UsageMeter";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+const meta: Meta<typeof UsageMeter> = {
+  title: "Billing/UsageMeter",
+  component: UsageMeter,
+  decorators: [
+    (Story) => (
+      <div style={{ maxWidth: 560 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof UsageMeter>;
+
+// A subscribed org on default settings: the $70 limit is $20 included
+// allowance + the $50 default spend limit, spelled out in the detail line
+// with the notch marking where the included allowance ends.
+export const SubscribedWithBreakdown: Story = {
+  args: {
+    label: "Usage this period",
+    percent: 18,
+    valueLabel: "$12.40 of $70",
+    detail: "$20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
+    markerPercent: (20 / 70) * 100,
+  },
+};
+
+export const SubscribedPastIncluded: Story = {
+  args: {
+    label: "Usage this period",
+    percent: 66,
+    valueLabel: "$46.20 of $70",
+    detail: "$20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
+    markerPercent: (20 / 70) * 100,
+  },
+};
+
+export const FreeTier: Story = {
+  args: {
+    label: "Monthly free usage",
+    percent: 62,
+    valueLabel: "$12.40 of $20 included",
+    detail: "Resets Jul 31 at 2:00 PM PDT",
+  },
+};
+
+export const Exceeded: Story = {
+  args: {
+    label: "Usage this period",
+    percent: 100,
+    valueLabel: "$70 of $70",
+    detail:
+      "Limit exceeded. $20 included + $50 org spend limit. Resets Jul 31 at 2:00 PM PDT",
+    markerPercent: (20 / 70) * 100,
+    color: "red",
+  },
+};
diff --git a/packages/ui/src/features/billing/UsageMeter.tsx b/packages/ui/src/features/billing/UsageMeter.tsx
@@ -6,6 +6,9 @@ interface UsageMeterProps {
   valueLabel: string;
   detail: string;
   color?: "red";
+  // Where a boundary inside the limit falls (e.g. the end of the included
+  // allowance), as a percent of the bar. Rendered as a notch over the track.
+  markerPercent?: number;
 }
 
 export function UsageMeter({
@@ -14,8 +17,11 @@ export function UsageMeter({
   valueLabel,
   detail,
   color,
+  markerPercent,
 }: UsageMeterProps) {
   const borderColor = color === "red" ? "var(--red-7)" : "var(--gray-5)";
+  const showMarker =
+    markerPercent != null && markerPercent > 0 && markerPercent < 100;
 
   return (
     <Flex
@@ -31,11 +37,20 @@ export function UsageMeter({
         <Text className="font-medium text-sm">{label}</Text>
         <Text className="font-medium text-sm">{valueLabel}</Text>
       </Flex>
-      <Progress
-        value={percent}
-        size="2"
-        color={color === "red" ? "red" : undefined}
-      />
+      <div className="relative">
+        <Progress
+          value={percent}
+          size="2"
+          color={color === "red" ? "red" : undefined}
+        />
+        {showMarker && (
+          <div
+            aria-hidden
+            className="absolute inset-y-0 w-px bg-(--gray-1)"
+            style={{ left: `${markerPercent}%` }}
+          />
+        )}
+      </div>
       <Text className="text-(--gray-9) text-[13px]">{detail}</Text>
     </Flex>
   );
diff --git a/packages/ui/src/features/settings/sections/PlanUsageSettings.tsx b/packages/ui/src/features/settings/sections/PlanUsageSettings.tsx
