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/routes/app/billing_.plans.tsx

@@ -35,10 +35,16 @@ const CHECKOUT_RETURN_PARAM = "checkout";
  * 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), then strip the marker so a later manual reload
- * does not re-arm the poll.
+ * 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): void {
+function useRefreshAfterCheckout(plans: Plan[] | undefined, refetch: () => void): string | null {
+  const [finalizingPlan, setFinalizingPlan] = useState<string | null>(null);
   const plansRef = useRef(plans);
   plansRef.current = plans;
 
@@ -50,6 +56,7 @@ function useRefreshAfterCheckout(plans: Plan[] | undefined, refetch: () => void)
     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 ===
@@ -61,12 +68,26 @@ function useRefreshAfterCheckout(plans: Plan[] | undefined, refetch: () => void)
       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 = [
@@ -133,7 +154,7 @@ function PlansPage() {
     void refetchCustomer();
     void refetchPlans();
   }, [refetchCustomer, refetchPlans]);
-  useRefreshAfterCheckout(plans, refetchBilling);
+  const finalizingPlan = useRefreshAfterCheckout(plans, refetchBilling);
 
   const isLoading = customerLoading || plansLoading;
 
@@ -193,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;
@@ -223,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>
                     )}
@@ -249,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 ? (

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

@@ -1,18 +1,20 @@
 // Cloud-only (billing, browser): completing the Team free-trial checkout should
-// leave the billing page showing the new plan WITHOUT a manual reload.
+// leave the billing page showing the new plan WITHOUT a manual reload, and
+// without ever flashing the stale upgrade CTA.
 //
-// Repro of a reported bug: a user starts the free trial, completes Stripe
-// checkout, and is redirected back to the plans page, which STILL shows the
-// upgrade/"Start free trial" call to action. A manual reload then shows the
-// active trial. The cause is client-side: autumn-js fetches the customer once
-// on load (staleTime 60s, refetchOnWindowFocus off) and the redirect back from
-// Stripe lands before Autumn has processed Stripe's webhook, so that single
-// fetch sees the old plan and the page never refetches on its own.
+// 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 this faithfully: completing the hosted checkout redirects
-// back immediately but does NOT activate the subscription; the activation lands
-// only when the webhook settles (autumn.settleCheckout). The reload control
-// proves the backend is consistent, isolating the failure to the stale client.
+// 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";
 
@@ -63,36 +65,25 @@ scenario(
 
       await step("Complete checkout and return to the plans page", async () => {
         await page.locator("button.checkout-pay-btn").click();
-        // Checkout completes and redirects back to the success_url (the plans
-        // page). The webhook has NOT landed yet, so the trial is still offered:
-        // exactly the window the bug lives in.
         await page.waitForURL(/billing\/plans/, { timeout: 30_000 });
-        await startTrial.waitFor();
+        // 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.
-      // From here on the billing backend is authoritative-consistent.
       await Effect.runPromise(autumn.settleCheckout(sessionId));
 
-      // The page the user was returned to never reloads. If the UI refetched
-      // after returning from checkout it would drop the trial CTA within a few
-      // seconds; today it does not, so this stays visible.
-      const reflectedWithoutReload = await startTrial
-        .waitFor({ state: "hidden", timeout: 8_000 })
-        .then(() => true)
-        .catch(() => false);
-
-      // Control: a manual reload surfaces the active trial, proving the backend
-      // was consistent all along and the only thing missing was a client refetch.
-      await step("A manual reload shows the active trial", async () => {
-        await page.reload({ waitUntil: "networkidle" });
+      // 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(
-        reflectedWithoutReload,
-        "the plans page reflects the completed checkout without a manual reload",
-      ).toBe(true);
+      expect(await startTrial.count(), "the upgrade CTA never returns").toBe(0);
     });
   }),
 );