feat(billing): classify gateway billing denials and rework limit modal for usage-based billing

First of the usage-based billing cutover stack (errors/copy -> billing
surfaces -> model gating):

- classifyGatewayLimitError/extractGatedModel in @posthog/shared; the
  free-tier model-gate 403 no longer classifies as a fatal session error.
- sessionService routes gateway billing denials to the usage-limit modal
  with a cause; the modal renders cause-aware usage-based copy behind the
  new posthog-code-usage-billing flag (off = seat-era copy unchanged).
- Helper prompts route to the free-tier model for orgs known unbilled via
  the optional code_usage_billed usage field, with a single gate-403 retry
  as the cold-start backstop.
- Seat handling keys off the API's 410 seat_product_retired: auto-provision
  stops re-attempting and explicit upgrades surface a clear message.

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

Author: adboio

packages/api-client/src/posthog-client.ts

@@ -133,6 +133,18 @@ export class SeatPaymentFailedError extends Error {
   }
 }
 
+/**
+ * Seat creation, upgrades, and reactivation return 410 Gone once PostHog Code
+ * seats are retired in favor of usage-based billing (reads and cancellation
+ * keep working for existing seats).
+ */
+export class SeatProductRetiredError extends Error {
+  constructor() {
+    super("PostHog Code seats have been retired");
+    this.name = "SeatProductRetiredError";
+  }
+}
+
 export class SandboxCustomImagesDisabledError extends Error {
   constructor(message?: string) {
     super(message ?? "Custom sandbox images are not enabled");
@@ -4589,6 +4601,9 @@ export class PostHogAPIClient {
     const parsed = this.parseFetcherError(error);
 
     if (parsed) {
+      if (parsed.status === 410) {
+        throw new SeatProductRetiredError();
+      }
       if (
         parsed.status === 400 &&
         typeof parsed.body.redirect_url === "string"

packages/core/src/billing/seatErrors.ts

@@ -3,11 +3,27 @@ export interface ClassifiedSeatError {
   redirectUrl: string | null;
 }
 
+/**
+ * The seat API's 410 Gone: PostHog Code seats are retired in favor of
+ * usage-based billing. Name-based so it survives the SeatClient seam.
+ */
+export function isSeatProductRetiredError(error: unknown): boolean {
+  return error instanceof Error && error.name === "SeatProductRetiredError";
+}
+
 export function classifySeatError(error: unknown): ClassifiedSeatError {
   if (!(error instanceof Error)) {
     return { error: "An unexpected error occurred", redirectUrl: null };
   }
 
+  if (isSeatProductRetiredError(error)) {
+    return {
+      error:
+        "PostHog Code seat plans have been retired — usage is now billed to your organization.",
+      redirectUrl: null,
+    };
+  }
+
   if (error.name === "SeatSubscriptionRequiredError") {
     const redirectUrl =
       "redirectUrl" in error && typeof error.redirectUrl === "string"

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

@@ -62,6 +62,13 @@ class SeatPaymentFailedError extends Error {
   }
 }
 
+class SeatProductRetiredError extends Error {
+  constructor() {
+    super("PostHog Code seats have been retired");
+    this.name = "SeatProductRetiredError";
+  }
+}
+
 beforeEach(() => {
   vi.clearAllMocks();
 });
@@ -278,3 +285,57 @@ describe("error classification", () => {
     expect(result.error).toBe("Card declined");
   });
 });
+
+// The seat API 410s creation/upgrades/reactivation once Code seats are
+// retired in favor of usage-based billing (reads keep working).
+describe("seat product retired (410 Gone)", () => {
+  it("treats a retired auto-provision as seatless instead of erroring", async () => {
+    const client = makeClient({
+      createSeat: vi.fn().mockRejectedValue(new SeatProductRetiredError()),
+    });
+    const result = await new SeatService(client, logger).fetchSeat({
+      autoProvision: true,
+    });
+    expect(result.seat).toBeNull();
+    expect(result.error).toBeNull();
+  });
+
+  it("stops re-attempting provisioning once the product is known retired", async () => {
+    const createSeat = vi.fn().mockRejectedValue(new SeatProductRetiredError());
+    const client = makeClient({ createSeat });
+    const service = new SeatService(client, logger);
+
+    await service.fetchSeat({ autoProvision: true });
+    createSeat.mockClear();
+    await service.fetchSeat({ autoProvision: true });
+
+    expect(createSeat).not.toHaveBeenCalled();
+  });
+
+  it("still re-fetches the seat after a non-retirement provisioning failure", async () => {
+    const seat = makeSeat();
+    const getMySeat = vi
+      .fn()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue(seat);
+    const client = makeClient({
+      getMySeat,
+      createSeat: vi.fn().mockRejectedValue(new Error("conflict")),
+    });
+    const result = await new SeatService(client, logger).fetchSeat({
+      autoProvision: true,
+    });
+    expect(result.error).toBeNull();
+    expect(result.seat).toEqual(seat);
+  });
+
+  it("surfaces retirement as a clear error on an explicit upgrade", async () => {
+    const client = makeClient({
+      createSeat: vi.fn().mockRejectedValue(new SeatProductRetiredError()),
+    });
+    const result = await new SeatService(client, logger).upgradeToPro();
+    expect(result.error).toContain("retired");
+    expect(result.redirectUrl).toBeNull();
+  });
+});

packages/core/src/billing/seatService.ts

@@ -2,7 +2,11 @@ import { ROOT_LOGGER, type RootLogger } from "@posthog/di/logger";
 import { PLAN_FREE, PLAN_PRO, type SeatData } from "@posthog/shared";
 import { inject, injectable } from "inversify";
 import { SEAT_CLIENT, type SeatClient, type SeatLogger } from "./identifiers";
-import { type ClassifiedSeatError, classifySeatError } from "./seatErrors";
+import {
+  type ClassifiedSeatError,
+  classifySeatError,
+  isSeatProductRetiredError,
+} from "./seatErrors";
 
 export interface SeatOperationResult {
   seat: SeatData | null;
@@ -43,6 +47,11 @@ function fail(classified: ClassifiedSeatError): SeatOperationResult {
 export class SeatService {
   private readonly logger: SeatLogger;
 
+  // The seat API 410s creation/upgrades/reactivation once seats are retired
+  // (usage-based billing). Remembered so auth/onboarding fetches stop
+  // re-attempting a provision that can never succeed.
+  private seatProductRetired = false;
+
   constructor(
     @inject(SEAT_CLIENT) private readonly client: SeatClient,
     @inject(ROOT_LOGGER) logger: RootLogger,
@@ -55,13 +64,18 @@ export class SeatService {
     autoProvision: boolean;
   }): Promise<SeatData | null> {
     let seat = await this.client.getMySeat({ best: options.best });
-    if (!seat && options.autoProvision) {
+    if (!seat && options.autoProvision && !this.seatProductRetired) {
       this.logger.info("No seat found, auto-provisioning free plan", {
         best: options.best,
       });
       try {
         seat = await this.client.createSeat(PLAN_FREE);
-      } catch {
+      } catch (error) {
+        if (isSeatProductRetiredError(error)) {
+          this.seatProductRetired = true;
+          this.logger.info("Seat product retired; skipping auto-provision");
+          return null;
+        }
         this.logger.info("Auto-provision failed, re-fetching seat");
         seat = await this.client.getMySeat({ best: options.best });
       }
@@ -118,6 +132,7 @@ export class SeatService {
       this.client.invalidatePlanCache();
       return ok(seat, null, true);
     } catch (error) {
+      if (isSeatProductRetiredError(error)) this.seatProductRetired = true;
       this.logger.error("provisionFreeSeat failed", error);
       return fail(classifySeatError(error));
     }
@@ -143,6 +158,7 @@ export class SeatService {
       this.client.invalidatePlanCache();
       return ok(seat, seat);
     } catch (error) {
+      if (isSeatProductRetiredError(error)) this.seatProductRetired = true;
       return fail(classifySeatError(error));
     }
   }
@@ -168,6 +184,7 @@ export class SeatService {
       this.client.invalidatePlanCache();
       return ok(seat, seat);
     } catch (error) {
+      if (isSeatProductRetiredError(error)) this.seatProductRetired = true;
       return fail(classifySeatError(error));
     }
   }

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

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import {
+  deriveUsageLimitCause,
+  seatEraLimitContent,
+  usageBasedLimitContent,
+} from "./usageLimitContent";
+
+describe("deriveUsageLimitCause", () => {
+  it.each([
+    ["model_gate", "burst", "model_gate"],
+    [null, "burst", "user_daily_limit"],
+    [null, "sustained", "user_monthly_limit"],
+    // No cause and no bucket (e.g. an upstream provider's own rate limit):
+    // stay generic instead of blaming the org's billing.
+    [null, null, null],
+  ] as const)("cause %s + bucket %s -> %s", (cause, bucket, expected) => {
+    expect(deriveUsageLimitCause(cause, bucket)).toBe(expected);
+  });
+});
+
+describe("usageBasedLimitContent", () => {
+  it("names the gated model and offers a payment method", () => {
+    const content = usageBasedLimitContent({
+      cause: "model_gate",
+      model: "Claude Opus 4.8",
+      resetLabel: null,
+      billed: false,
+    });
+    expect(content.title).toBe("Unlock premium models");
+    expect(content.description).toContain("Claude Opus 4.8 isn't");
+    expect(content.actionLabel).toBe("Add payment method");
+  });
+
+  it("falls back to generic wording when the gated model is unknown", () => {
+    const content = usageBasedLimitContent({
+      cause: "model_gate",
+      model: null,
+      resetLabel: null,
+      billed: undefined,
+    });
+    expect(content.description).toContain("This model isn't");
+  });
+
+  it.each([
+    // Confirmed-free 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.
+    [true, "Organization usage limit reached", "Manage billing"],
+    // Unknown billed 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) => {
+      const content = usageBasedLimitContent({
+        cause: "org_limit",
+        model: null,
+        resetLabel: null,
+        billed,
+      });
+      expect(content.title).toBe(title);
+      expect(content.actionLabel).toBe(actionLabel);
+    },
+  );
+
+  it.each([
+    ["user_daily_limit", "Free daily limit reached"],
+    ["user_monthly_limit", "Free monthly limit reached"],
+  ] as const)("%s carries the reset hint", (cause, title) => {
+    const content = usageBasedLimitContent({
+      cause,
+      model: null,
+      resetLabel: "Resets in 2h",
+      billed: false,
+    });
+    expect(content.title).toBe(title);
+    expect(content.description).toContain("Resets in 2h");
+    expect(content.actionLabel).toBe("Add payment method");
+  });
+
+  it("renders generic copy without a billing CTA when the cause is unknown", () => {
+    const content = usageBasedLimitContent({
+      cause: null,
+      model: null,
+      resetLabel: null,
+      billed: true,
+    });
+    expect(content.title).toBe("Usage limit reached");
+    expect(content.actionLabel).toBeNull();
+    expect(content.dismissLabel).toBe("Got it");
+  });
+});
+
+describe("seatEraLimitContent", () => {
+  it("keeps the Pro cap copy with no upgrade action", () => {
+    const content = seatEraLimitContent({
+      bucket: "sustained",
+      isPro: true,
+      resetLabel: "Resets in 3d",
+    });
+    expect(content.title).toBe("Monthly limit reached");
+    expect(content.description).toContain("monthly usage cap");
+    expect(content.actionLabel).toBeNull();
+    expect(content.dismissLabel).toBe("Got it");
+  });
+
+  it("keeps the free-plan upgrade pitch", () => {
+    const content = seatEraLimitContent({
+      bucket: "burst",
+      isPro: false,
+      resetLabel: null,
+    });
+    expect(content.title).toBe("Daily limit reached");
+    expect(content.description).toContain("Upgrade to Pro for 40×");
+    expect(content.actionLabel).toBe("See Pro");
+  });
+});