fix(billing): refresh plan after returning from checkout (#1215)

* fix(billing): refresh plan after returning from checkout

After completing a redirect checkout (e.g. the Team free trial), the browser
is sent back to the plans page before Stripe's checkout.session.completed
webhook reaches Autumn. autumn-js fetches the customer once on load and does
not refetch on its own (staleTime 60s, refetchOnWindowFocus off), so the page
showed the old plan and the upgrade CTA until a manual reload.

Tag the checkout success URL with the attached plan id and, on return, poll the
billing data until that plan shows active (or a timeout), then strip the marker.

Also fix the billing proxy passing the wrong key to autumn-js: the handler
reads clientOptions.baseURL, not serverURL, so AUTUMN_API_URL (the e2e emulator
or a self-hosted Autumn) was silently dropped and every billing request hit
production Autumn and 401'd.

Adds a cloud e2e scenario that drives the full trial-checkout flow against the
Autumn emulator and asserts the plan updates without a reload, plus the plan
catalog seed the billing UI needs.

* test(e2e): consume @executor-js/emulate 0.9.0 for the trial-checkout scenario

* fix(billing): show purchased plan as activating on checkout return

Instead of refetching into the stale upgrade CTA (which flashes 'Start free
trial' on a plan the user just paid for), the page reads the purchased plan
from the return marker and shows it as Activating while it polls, resolving to
the active plan once the webhook lands. No manual reload, no stale state.

Author: RhysSullivan

apps/cloud/src/extensions/billing/route.ts

@@ -86,7 +86,11 @@ const handler = Effect.gen(function* () {
       },
       clientOptions: {
         secretKey: env.AUTUMN_SECRET_KEY ?? "",
-        ...(env.AUTUMN_API_URL ? { serverURL: env.AUTUMN_API_URL } : {}),
+        // autumn-js's handler reads `baseURL` to override the Autumn endpoint
+        // (not `serverURL`, which it silently ignores). Without this, a non-prod
+        // AUTUMN_API_URL (the e2e emulator, a self-hosted Autumn) is dropped and
+        // every billing request goes to production Autumn and 401s.
+        ...(env.AUTUMN_API_URL ? { baseURL: env.AUTUMN_API_URL } : {}),
       },
       pathPrefix: "/api/billing",
     }),

apps/cloud/src/routes/app/billing_.plans.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { createFileRoute, Link } from "@tanstack/react-router";
 import { useCustomer, useListPlans } from "autumn-js/react";
 import { trackEvent } from "@executor-js/react/api/analytics";
@@ -21,6 +21,75 @@ export const Route = createFileRoute("/{-$orgSlug}/billing_/plans")({
   component: PlansPage,
 });
 
+// Marker appended to the checkout success URL so the page knows, on return, that
+// it just came back from Stripe and which plan was attached.
+const CHECKOUT_RETURN_PARAM = "checkout";
+
+/**
+ * Refresh billing data after returning from a redirect checkout.
+ *
+ * autumn-js fetches the customer once on load and does not refetch on its own
+ * (staleTime 60s, no refetch on focus), while Stripe's `checkout.session.completed`
+ * webhook reaches Autumn moments AFTER the browser is redirected back. So the
+ * single fetch on the success page sees the pre-checkout plan and the page would
+ * otherwise show the old plan (and the upgrade CTA) until a manual reload.
+ *
+ * On detecting the return marker, poll the billing data until the attached plan
+ * shows as active (or a timeout). While that reconciliation is in flight this
+ * returns the attached plan id so the page can show that plan as "Activating"
+ * rather than the pre-checkout upgrade CTA, which would otherwise read as if the
+ * purchase did not happen. The marker is stripped immediately so a later manual
+ * reload does not re-arm the poll.
+ *
+ * @returns the plan id being finalized, or null once it reflects (or times out).
+ */
+function useRefreshAfterCheckout(plans: Plan[] | undefined, refetch: () => void): string | null {
+  const [finalizingPlan, setFinalizingPlan] = useState<string | null>(null);
+  const plansRef = useRef(plans);
+  plansRef.current = plans;
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const attachedPlanId = params.get(CHECKOUT_RETURN_PARAM);
+    if (!attachedPlanId) return;
+
+    params.delete(CHECKOUT_RETURN_PARAM);
+    const query = params.toString();
+    window.history.replaceState({}, "", `${window.location.pathname}${query ? `?${query}` : ""}`);
+    setFinalizingPlan(attachedPlanId);
+
+    const reflected = () =>
+      plansRef.current?.find((p) => p.id === attachedPlanId)?.customerEligibility?.status ===
+      "active";
+
+    let elapsed = 0;
+    refetch();
+    const interval = setInterval(() => {
+      elapsed += 1500;
+      if (reflected() || elapsed >= 20_000) {
+        clearInterval(interval);
+        setFinalizingPlan(null);
+        return;
+      }
+      refetch();
+    }, 1500);
+    return () => clearInterval(interval);
+  }, [refetch]);
+
+  // Drop the optimistic state the moment the refetched data reflects the plan,
+  // so it does not linger until the next poll tick after the webhook lands.
+  useEffect(() => {
+    if (
+      finalizingPlan &&
+      plans?.find((p) => p.id === finalizingPlan)?.customerEligibility?.status === "active"
+    ) {
+      setFinalizingPlan(null);
+    }
+  }, [finalizingPlan, plans]);
+
+  return finalizingPlan;
+}
+
 const ENTERPRISE_FEATURES = [
   "Self-hosted or dedicated cloud deployment support",
   "SSO / SAML & SCIM provisioning",
@@ -67,10 +136,26 @@ const ACTION_LABELS: Record<string, string> = {
 const PLAN_ORDER = ["free", "team", "enterprise"];
 
 function PlansPage() {
-  const { attach, openCustomerPortal, isLoading: customerLoading } = useCustomer();
-  const { data: plans, isLoading: plansLoading, isFetching } = useListPlans();
+  const {
+    attach,
+    openCustomerPortal,
+    isLoading: customerLoading,
+    refetch: refetchCustomer,
+  } = useCustomer();
+  const {
+    data: plans,
+    isLoading: plansLoading,
+    isFetching,
+    refetch: refetchPlans,
+  } = useListPlans();
   const [loadingPlan, setLoadingPlan] = useState<string | null>(null);
 
+  const refetchBilling = useCallback(() => {
+    void refetchCustomer();
+    void refetchPlans();
+  }, [refetchCustomer, refetchPlans]);
+  const finalizingPlan = useRefreshAfterCheckout(plans, refetchBilling);
+
   const isLoading = customerLoading || plansLoading;
 
   const selfServePlans = PLAN_ORDER.flatMap((id) =>
@@ -129,6 +214,9 @@ function PlansPage() {
               const isScheduled = status === "scheduled";
               const isUpgradeAction = action === "upgrade" || action === "activate";
               const isEnterprise = plan.id === "enterprise";
+              // Just back from checkout for this plan and the webhook has not
+              // landed yet: show it as activating instead of the stale CTA.
+              const isFinalizing = plan.id === finalizingPlan && !isCurrent && !isScheduled;
               // Offer the trial only when the plan defines one and this customer
               // is still eligible (trialAvailable is false once they've used it).
               const freeTrial = plan.freeTrial;
@@ -159,6 +247,9 @@ function PlansPage() {
                       {plan.name}
                     </p>
                     {isCurrent && <Badge className="bg-muted text-foreground">Your plan</Badge>}
+                    {isFinalizing && (
+                      <Badge className="bg-primary/10 text-primary">Activating</Badge>
+                    )}
                     {isCanceling && (
                       <Badge className="bg-muted text-muted-foreground">Canceling</Badge>
                     )}
@@ -185,6 +276,11 @@ function PlansPage() {
                       <div className="flex h-9 items-center justify-center rounded-md border border-border bg-muted/30 text-sm font-medium text-muted-foreground">
                         {isCurrent ? "Current plan" : "Scheduled"}
                       </div>
+                    ) : isFinalizing ? (
+                      <div className="flex h-9 items-center justify-center gap-2 rounded-md border border-border bg-muted/30 text-sm font-medium text-muted-foreground">
+                        <span className="size-3.5 animate-spin rounded-full border-2 border-muted-foreground/30 border-t-muted-foreground" />
+                        Activating…
+                      </div>
                     ) : isEnterprise ? (
                       <EnterpriseContactDialog />
                     ) : isCanceling ? (
@@ -215,7 +311,11 @@ function PlansPage() {
                             });
                           }
                           setLoadingPlan(plan.id);
-                          await attach({ planId: plan.id, redirectMode: "always" });
+                          // Tag the return URL so the page refetches billing
+                          // data when Stripe redirects back (the webhook that
+                          // activates the plan lands moments after the redirect).
+                          const successUrl = `${window.location.origin}${window.location.pathname}?${CHECKOUT_RETURN_PARAM}=${plan.id}`;
+                          await attach({ planId: plan.id, redirectMode: "always", successUrl });
                           setLoadingPlan(null);
                         }}
                         className={[

bun.lock

@@ -0,0 +1,89 @@
+// Cloud-only (billing, browser): completing the Team free-trial checkout should
+// leave the billing page showing the new plan WITHOUT a manual reload, and
+// without ever flashing the stale upgrade CTA.
+//
+// Guards a reported bug + its fix: a user starts the free trial, completes
+// Stripe checkout, and is redirected back to the plans page. The redirect lands
+// before Autumn has processed Stripe's webhook, and autumn-js fetches the
+// customer once on load (staleTime 60s, refetchOnWindowFocus off), so the page
+// used to show the old plan and the "Start free trial" CTA until a manual
+// reload. The fix tags the checkout return URL with the purchased plan, then on
+// return shows that plan as "Activating" while it refetches until the webhook
+// lands, resolving to "Your plan" with no reload.
+//
+// The emulator models the race faithfully: completing the hosted checkout
+// redirects back immediately but does NOT activate the subscription; activation
+// lands only when the webhook settles (autumn.settleCheckout), which this test
+// triggers to control the exact moment the backend becomes consistent.
+import { expect } from "@effect/vitest";
+import { Effect } from "effect";
+
+import { scenario } from "../src/scenario";
+import { Autumn, Billing, Browser, Target } from "../src/services";
+
+scenario(
+  "Billing · completing the trial checkout shows the new plan without a reload",
+  { timeout: 120_000 },
+  Effect.gen(function* () {
+    // Gates: billing enforced here AND the Autumn emulator is observable (so we
+    // can land the checkout webhook). Yield before any work so a target missing
+    // either capability skips cleanly rather than failing.
+    yield* Billing;
+    const autumn = yield* Autumn;
+    const target = yield* Target;
+    const browser = yield* Browser;
+
+    const identity = yield* target.newIdentity();
+
+    yield* browser.session(identity, async ({ page, step }) => {
+      const teamCard = page
+        .getByText("Team", { exact: true })
+        .locator("xpath=ancestor::div[contains(@class,'rounded-xl')][1]");
+      const startTrial = teamCard.getByRole("button", { name: "Start free trial" });
+
+      await step("A fresh org is offered the Team free trial", async () => {
+        // Billing requests are org-scoped via the URL slug header, so reach the
+        // plans page through the org-scoped URL (a bare /billing/plans would fire
+        // the first fetch before the slug resolves and 401). Land on "/" to
+        // canonicalize, then open the slug-scoped plans page.
+        await page.goto("/", { waitUntil: "networkidle" });
+        const slug = new URL(page.url()).pathname.split("/").filter(Boolean)[0];
+        await page.goto(`/${slug}/billing/plans`, { waitUntil: "networkidle" });
+        await page.getByRole("heading", { name: "Choose a plan" }).waitFor();
+        await startTrial.waitFor();
+      });
+
+      let sessionId = "";
+      await step("Start the trial and land on the hosted checkout", async () => {
+        await startTrial.click();
+        // attach() redirects the whole page to the checkout URL.
+        await page.waitForURL(/\/checkout\//, { timeout: 30_000 });
+        sessionId = new URL(page.url()).pathname.split("/").filter(Boolean).pop() ?? "";
+        expect(sessionId, "captured the checkout session id").toMatch(/^cs_/);
+        await page.locator("button.checkout-pay-btn").waitFor();
+      });
+
+      await step("Complete checkout and return to the plans page", async () => {
+        await page.locator("button.checkout-pay-btn").click();
+        await page.waitForURL(/billing\/plans/, { timeout: 30_000 });
+        // The webhook has NOT landed yet, but the page knows from the return
+        // marker which plan was purchased, so it shows that plan as activating
+        // rather than the stale upgrade CTA (which would read as if nothing
+        // happened). This is the key user-facing guarantee.
+        await teamCard.getByText("Activating", { exact: true }).waitFor({ timeout: 10_000 });
+        expect(await startTrial.count(), "the stale trial CTA is not shown on return").toBe(0);
+      });
+
+      // The Stripe webhook reaches Autumn: the customer is now on the Team trial.
+      await Effect.runPromise(autumn.settleCheckout(sessionId));
+
+      // Without any reload, the activating state resolves to the active plan as
+      // the polled refetch picks up the now-consistent backend.
+      await step("The plan resolves to active without a reload", async () => {
+        await teamCard.getByText("Current plan").waitFor({ timeout: 15_000 });
+        await teamCard.getByText("Your plan").waitFor({ timeout: 5_000 });
+      });
+      expect(await startTrial.count(), "the upgrade CTA never returns").toBe(0);
+    });
+  }),
+);

e2e/cloud/billing-trial-checkout-stale.test.ts

@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@executor-js/api": "workspace:*",
-    "@executor-js/emulate": "^0.8.1",
+    "@executor-js/emulate": "^0.9.0",
     "@executor-js/mcporter": "^0.11.4",
     "@executor-js/plugin-graphql": "workspace:*",
     "@executor-js/plugin-mcp": "workspace:*",

e2e/package.json

@@ -0,0 +1,51 @@
+// The plan catalog the Autumn emulator advertises, derived from the deploy-time
+// source of truth (repo-root `autumn.config.ts`). In production Autumn learns
+// these plans via `atmn` sync; the emulator has no such sync, so the e2e boot
+// seeds them. Keeping this derived from autumn.config.ts means plans, prices,
+// and the Team free trial can never drift from what the app actually ships.
+import { free, team, enterprise } from "../../autumn.config";
+
+type AtmnPlan = {
+  id: string;
+  name: string;
+  addOn?: boolean;
+  autoEnable?: boolean;
+  price?: { amount: number; interval: string };
+  freeTrial?: { durationLength: number; durationType: string; cardRequired?: boolean };
+  items?: ReadonlyArray<{ featureId: string; included?: number; unlimited?: boolean }>;
+};
+
+export interface AutumnSeedPlan {
+  id: string;
+  name: string;
+  add_on: boolean;
+  auto_enable: boolean;
+  price: { amount: number; interval: string } | null;
+  free_trial: { duration_length: number; duration_type: string; card_required: boolean } | null;
+  items: Array<{ feature_id: string; included?: number; unlimited?: boolean }>;
+}
+
+const toSeed = (plan: AtmnPlan): AutumnSeedPlan => ({
+  id: plan.id,
+  name: plan.name,
+  add_on: plan.addOn ?? false,
+  auto_enable: plan.autoEnable ?? false,
+  price: plan.price ? { amount: plan.price.amount, interval: plan.price.interval } : null,
+  free_trial: plan.freeTrial
+    ? {
+        duration_length: plan.freeTrial.durationLength,
+        duration_type: plan.freeTrial.durationType,
+        card_required: plan.freeTrial.cardRequired ?? false,
+      }
+    : null,
+  items: (plan.items ?? []).map((it) => ({
+    feature_id: it.featureId,
+    included: it.included,
+    unlimited: it.unlimited,
+  })),
+});
+
+/** Free, Team (card-required 14-day trial), and Enterprise, in display order. */
+export const AUTUMN_PLAN_SEED: AutumnSeedPlan[] = [free, team, enterprise].map((p) =>
+  toSeed(p as AtmnPlan),
+);

e2e/setup/autumn-plans.ts

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import { createEmulator } from "@executor-js/emulate";
 
 import { bootProcesses, waitForHttp } from "./boot";
+import { AUTUMN_PLAN_SEED } from "./autumn-plans";
 
 export const cloudDir = fileURLToPath(new URL("../../apps/cloud/", import.meta.url));
 
@@ -65,6 +66,9 @@ export const bootCloud = async (options: CloudBootOptions): Promise<CloudBooted>
   const autumn = await createEmulator({
     service: "autumn",
     port: options.autumnPort,
+    // Seed the plan catalog so the billing UI (plans, eligibility, trial
+    // checkout) has real plans to render. Derived from autumn.config.ts.
+    seed: { autumn: { plans: AUTUMN_PLAN_SEED } },
   });
 
   const workosUrl = options.workosPublicUrl ?? workos.url;