v2 onboarding: dedicated verify step and upgrade-free-trial as the last step (#22303)

https://github.com/user-attachments/assets/b1ee4f77-c6d7-4638-b9f1-dd801d1cc0db

Completes the onboarding-v2 flow: a dedicated verify step, the
reordering that makes the plan step come last, and the
upgrade-free-trial page itself.

## Verify step (`/verify-v2`)
After the cross-domain token exchange, v2 sign-ups land on a clean
`BlankLayout` "Verifying your email" screen (fading Twenty logo) instead
of the v1 `AuthModal` flashing over the background mock. The redirect
target is chosen from `isOnboardingV2` (read from the Jotai store at
redirect time). The pulsing logo is extracted into a shared
`OnboardingPulsingLogo`, reused by the workspace-activation loader.
`/verify-v2` joins the same exempt lists as `/verify` (ongoing-creation
guard, metadata gater, apollo unauthenticated handler, captcha, page
title) — intentionally not `useShowAuthModal`, which is what drops the
modal.

## Plan step is now last
`getOnboardingStatus` checks `PLAN_REQUIRED` after invite-team instead
of first, so onboarding runs workspace activation → email → profile →
invite → plan. This is what lets the upgrade step be reached as the
final step instead of gating right after sign-up. Applies to both v1 and
v2 (same order).

## Upgrade free trial page (`PlanRequiredV2` → `ChooseYourPlanV2` /
`UpgradeFreeTrial`)
The final step, full-screen under `BlankLayout` via
`OnboardingV2Layout`, matching the Figma (billing card with the Stripe
form, the "Basic / without credit card" option, trial + credits pills).
Reuses the v1 `ChooseYourPlanContent` billing logic
(`SubscriptionPaymentForm`, `useHandleCheckoutSession`). The "+N free
credits" reward comes from
`clientConfig.onboarding.upgradeCreditsReward` (sourced from
`BILLING_FREE_WORKFLOW_CREDITS_FOR_TRIAL_PERIOD_WITH_CREDIT_CARD`).

## Also
Fixes a latent staleness in the Apollo `onUnauthenticatedError` handler
— it captured `location` from the memoized client, now read via a ref —
so auth-path exemptions are correct after navigation.

Note: the onboarding step order change affects v1 too (plan becomes its
last step as well).

packages/twenty-front/src/modules/apollo/hooks/useApolloFactory.ts

@@ -39,6 +39,9 @@ export const useApolloFactory = (options: Partial<Options> = {}) => {
 
   const setReturnToPath = useSetAtomState(returnToPathState);
   const location = useLocation();
+  // oxlint-disable-next-line twenty/no-state-useref
+  const locationRef = useRef(location);
+  locationRef.current = location;
 
   const { enqueueErrorSnackBar } = useSnackBar();
 
@@ -72,12 +75,13 @@ export const useApolloFactory = (options: Partial<Options> = {}) => {
         setCurrentWorkspace(null);
         setCurrentUserWorkspace(null);
         if (
-          !isMatchingLocation(location, AppPath.Verify) &&
-          !isMatchingLocation(location, AppPath.SignInUp) &&
-          !isMatchingLocation(location, AppPath.Invite) &&
-          !isMatchingLocation(location, AppPath.ResetPassword)
+          !isMatchingLocation(locationRef.current, AppPath.Verify) &&
+          !isMatchingLocation(locationRef.current, AppPath.VerifyV2) &&
+          !isMatchingLocation(locationRef.current, AppPath.SignInUp) &&
+          !isMatchingLocation(locationRef.current, AppPath.Invite) &&
+          !isMatchingLocation(locationRef.current, AppPath.ResetPassword)
         ) {
-          const path = `${location.pathname}${location.search}${location.hash}`;
+          const path = `${locationRef.current.pathname}${locationRef.current.search}${locationRef.current.hash}`;
 
           if (isValidReturnToPath(path)) {
             setReturnToPath(path);

packages/twenty-front/src/modules/app/hooks/useCreateAppRouter.tsx

@@ -5,6 +5,7 @@ import { VerifyLoginTokenEffect } from '@/auth/components/VerifyLoginTokenEffect
 
 import { VerifyEmailEffect } from '@/auth/components/VerifyEmailEffect';
 import indexAppPath from '@/navigation/utils/indexAppPath';
+import { VerifyV2 } from '~/pages/onboarding/VerifyV2';
 import { RecordIndexSkeletonLoader } from '@/object-record/record-index/components/RecordIndexSkeletonLoader';
 import { BlankLayout } from '@/ui/layout/page/components/BlankLayout';
 import { DefaultLayout } from '@/ui/layout/page/components/DefaultLayout';
@@ -110,6 +111,12 @@ const ChooseYourPlan = lazy(() =>
   })),
 );
 
+const ChooseYourPlanV2 = lazy(() =>
+  import('~/pages/onboarding/ChooseYourPlanV2').then((module) => ({
+    default: module.ChooseYourPlanV2,
+  })),
+);
+
 const PaymentSuccess = lazy(() =>
   import('~/pages/onboarding/PaymentSuccess').then((module) => ({
     default: module.PaymentSuccess,
@@ -306,6 +313,7 @@ export const useCreateAppRouter = (
               </LazyRoute>
             }
           />
+          <Route path={AppPath.VerifyV2} element={<VerifyV2 />} />
           <Route
             path={AppPath.WorkspaceActivationV2}
             element={
@@ -338,6 +346,14 @@ export const useCreateAppRouter = (
               </LazyRoute>
             }
           />
+          <Route
+            path={AppPath.PlanRequiredV2}
+            element={
+              <LazyRoute fallback={null}>
+                <ChooseYourPlanV2 />
+              </LazyRoute>
+            }
+          />
           <Route
             path={AppPath.Authorize}
             element={

packages/twenty-front/src/modules/auth/constants/OnboardingPaths.ts

@@ -10,6 +10,7 @@ export const ONBOARDING_PATHS = [
   AppPath.InviteTeam,
   AppPath.InviteTeamV2,
   AppPath.PlanRequired,
+  AppPath.PlanRequiredV2,
   AppPath.PlanRequiredSuccess,
   AppPath.BookCallDecision,
   AppPath.BookCall,

packages/twenty-front/src/modules/auth/constants/OngoingUserCreationPaths.ts

@@ -6,4 +6,5 @@ export const ONGOING_USER_CREATION_PATHS = [
   AppPath.SignInUpV2,
   AppPath.VerifyEmail,
   AppPath.Verify,
+  AppPath.VerifyV2,
 ];

packages/twenty-front/src/modules/auth/sign-in-up/components/SignInUpWorkspaceActivationV2.tsx

@@ -1,38 +1,17 @@
 import { SubTitle } from '@/auth/components/SubTitle';
 import { WORKSPACE_ACTIVATION_MESSAGES } from '@/auth/sign-in-up/constants/WorkspaceActivationMessages';
+import { OnboardingPulsingLogo } from '@/onboarding/components/OnboardingPulsingLogo';
 import { styled } from '@linaria/react';
 import { useLingui } from '@lingui/react/macro';
 import { motion, useReducedMotion } from 'framer-motion';
 import { useContext } from 'react';
-import { ThemeContext, themeCssVariables } from 'twenty-ui/theme-constants';
+import { ThemeContext } from 'twenty-ui/theme-constants';
 
 const STEP_OPACITIES = [1, 0.4, 0.12];
 const VISIBLE_STEP_COUNT = STEP_OPACITIES.length;
 const STEP_HEIGHT_IN_PX = 28;
 const STEPS_CONTAINER_HEIGHT_IN_PX = STEP_HEIGHT_IN_PX * VISIBLE_STEP_COUNT;
 
-const StyledLogo = styled.img`
-  animation: signInUpWorkspaceActivationLogoPulse 0.8s ease-in-out infinite
-    alternate;
-  height: ${themeCssVariables.spacing[12]};
-  margin-bottom: ${themeCssVariables.spacing[8]};
-  width: ${themeCssVariables.spacing[12]};
-
-  @keyframes signInUpWorkspaceActivationLogoPulse {
-    from {
-      opacity: 1;
-    }
-    to {
-      opacity: 0.4;
-    }
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    animation: none;
-    opacity: 1;
-  }
-`;
-
 const StyledStepsContainer = styled.div`
   height: ${STEPS_CONTAINER_HEIGHT_IN_PX}px;
   position: relative;
@@ -65,7 +44,7 @@ export const SignInUpWorkspaceActivationV2 = ({
 
   return (
     <>
-      <StyledLogo src="/images/integrations/twenty-logo.svg" alt="" />
+      <OnboardingPulsingLogo />
       <StyledStepsContainer>
         {messages.map((message, index) => {
           const stepOffset = index - messageIndex;

packages/twenty-front/src/modules/auth/sign-in-up/hooks/useSignUpInNewWorkspace.ts

@@ -1,4 +1,5 @@
 import { useAuth } from '@/auth/hooks/useAuth';
+import { isOnboardingV2State } from '@/auth/states/isOnboardingV2State';
 import { isMultiWorkspaceEnabledState } from '@/client-config/states/isMultiWorkspaceEnabledState';
 import { useRedirectToWorkspaceDomain } from '@/domain-manager/hooks/useRedirectToWorkspaceDomain';
 import { useSnackBar } from '@/ui/feedback/snack-bar-manager/hooks/useSnackBar';
@@ -13,6 +14,7 @@ import {
 import { getWorkspaceUrl } from '~/utils/getWorkspaceUrl';
 import { assertIsDefinedOrThrow, isDefined } from 'twenty-shared/utils';
 import { useLingui } from '@lingui/react/macro';
+import { useStore } from 'jotai';
 
 export const useSignUpInNewWorkspace = () => {
   const { redirectToWorkspaceDomain } = useRedirectToWorkspaceDomain();
@@ -20,6 +22,7 @@ export const useSignUpInNewWorkspace = () => {
   const isMultiWorkspaceEnabled = useAtomStateValue(
     isMultiWorkspaceEnabledState,
   );
+  const store = useStore();
   const { enqueueErrorSnackBar } = useSnackBar();
   const { t } = useLingui();
 
@@ -73,9 +76,11 @@ export const useSignUpInNewWorkspace = () => {
         return true;
       }
 
+      const isOnboardingV2 = store.get(isOnboardingV2State.atom);
+
       await redirectToWorkspaceDomain(
         getWorkspaceUrl(data.signUpInNewWorkspace.workspace.workspaceUrls),
-        AppPath.Verify,
+        isOnboardingV2 ? AppPath.VerifyV2 : AppPath.Verify,
         { loginToken },
         '_self',
       );

packages/twenty-front/src/modules/captcha/constants/CaptchaProtectedPaths.ts

@@ -4,6 +4,7 @@ export const CAPTCHA_PROTECTED_PATHS: string[] = [
   AppPath.SignInUp,
   AppPath.SignInUpV2,
   AppPath.Verify,
+  AppPath.VerifyV2,
   AppPath.VerifyEmail,
   AppPath.ResetPassword,
   AppPath.Invite,

packages/twenty-front/src/modules/client-config/types/OnboardingConfig.ts

@@ -2,4 +2,5 @@ export type OnboardingConfig = {
   importContactsCreditsReward: number;
   inviteTeamMaxCreditsReward: number;
   inviteTeamCreditsRewardPerUser: number;
+  upgradeCreditsReward: number;
 };

packages/twenty-front/src/modules/metadata-store/components/MinimalMetadataGater.tsx

@@ -17,6 +17,7 @@ export const MinimalMetadataGater = ({ children }: React.PropsWithChildren) => {
 
   const isOnExcludedPath =
     isMatchingLocation(location, AppPath.Verify) ||
+    isMatchingLocation(location, AppPath.VerifyV2) ||
     isMatchingLocation(location, AppPath.VerifyEmail) ||
     isMatchingLocation(location, AppPath.SignInUp) ||
     isMatchingLocation(location, AppPath.SignInUpV2) ||

packages/twenty-front/src/modules/onboarding/components/OnboardingPulsingLogo.tsx

@@ -0,0 +1,27 @@
+import { styled } from '@linaria/react';
+import { themeCssVariables } from 'twenty-ui/theme-constants';
+
+const StyledLogo = styled.img`
+  animation: onboardingPulsingLogo 0.8s ease-in-out infinite alternate;
+  height: ${themeCssVariables.spacing[12]};
+  margin-bottom: ${themeCssVariables.spacing[8]};
+  width: ${themeCssVariables.spacing[12]};
+
+  @keyframes onboardingPulsingLogo {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0.4;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 1;
+  }
+`;
+
+export const OnboardingPulsingLogo = () => (
+  <StyledLogo src="/images/integrations/twenty-logo.svg" alt="" />
+);

packages/twenty-front/src/modules/onboarding/components/upgrade-free-trial/OnboardingPlanCard.tsx

@@ -0,0 +1,129 @@
+import { styled } from '@linaria/react';
+import { isValidElement, type ReactNode } from 'react';
+import { isDefined } from 'twenty-shared/utils';
+import { Radio } from 'twenty-ui/input';
+import { themeCssVariables } from 'twenty-ui/theme-constants';
+
+const StyledCard = styled.div`
+  background-color: ${themeCssVariables.background.primary};
+  border: 1px solid ${themeCssVariables.border.color.medium};
+  border-radius: ${themeCssVariables.border.radius.md};
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  width: 100%;
+`;
+
+const StyledHeader = styled.button<{ hasBody: boolean }>`
+  align-items: flex-start;
+  background-color: transparent;
+  border: none;
+  border-bottom: ${({ hasBody }) =>
+    hasBody ? `1px solid ${themeCssVariables.border.color.light}` : 'none'};
+  cursor: pointer;
+  display: flex;
+  gap: ${themeCssVariables.spacing[2]};
+  justify-content: space-between;
+  padding: ${themeCssVariables.spacing[4]} ${themeCssVariables.spacing[3]};
+  text-align: left;
+  width: 100%;
+`;
+
+const StyledHeaderLeft = styled.div`
+  display: flex;
+  flex: 1 1 0;
+  flex-direction: column;
+  gap: ${themeCssVariables.spacing[2]};
+  min-width: 0;
+`;
+
+const StyledTitleRow = styled.div`
+  align-items: center;
+  display: flex;
+  gap: ${themeCssVariables.spacing[1]};
+`;
+
+const StyledTitle = styled.span`
+  color: ${themeCssVariables.font.color.primary};
+  font-size: ${themeCssVariables.font.size.md};
+  font-weight: ${themeCssVariables.font.weight.medium};
+`;
+
+const StyledTitleSuffix = styled.span`
+  color: ${themeCssVariables.font.color.tertiary};
+  font-size: ${themeCssVariables.font.size.sm};
+  font-weight: ${themeCssVariables.font.weight.regular};
+`;
+
+const StyledNote = styled.span`
+  color: ${themeCssVariables.font.color.light};
+  font-size: ${themeCssVariables.font.size.sm};
+  font-weight: ${themeCssVariables.font.weight.regular};
+`;
+
+const StyledHeaderRight = styled.div`
+  align-items: center;
+  display: flex;
+  gap: ${themeCssVariables.spacing[2]};
+`;
+
+const StyledBadge = styled.span`
+  align-items: center;
+  background-color: ${themeCssVariables.background.tertiary};
+  border-radius: ${themeCssVariables.border.radius.pill};
+  color: ${themeCssVariables.font.color.tertiary};
+  display: flex;
+  font-size: ${themeCssVariables.font.size.sm};
+  font-weight: ${themeCssVariables.font.weight.medium};
+  padding: ${themeCssVariables.spacing[1]} ${themeCssVariables.spacing[2]};
+`;
+
+const StyledBody = styled.div`
+  display: flex;
+  flex-direction: column;
+  padding: ${themeCssVariables.spacing[4]} ${themeCssVariables.spacing[3]};
+`;
+
+type OnboardingPlanCardProps = {
+  title: string;
+  titleSuffix?: string;
+  note?: string;
+  badge?: string;
+  selected: boolean;
+  onSelect: () => void;
+  children?: ReactNode;
+};
+
+export const OnboardingPlanCard = ({
+  title,
+  titleSuffix,
+  note,
+  badge,
+  selected,
+  onSelect,
+  children,
+}: OnboardingPlanCardProps) => {
+  const hasBody = isValidElement(children);
+
+  return (
+    <StyledCard>
+      <StyledHeader type="button" hasBody={hasBody} onClick={onSelect}>
+        <StyledHeaderLeft>
+          <StyledTitleRow>
+            <StyledTitle>{title}</StyledTitle>
+            {isDefined(titleSuffix) && (
+              <StyledTitleSuffix>{titleSuffix}</StyledTitleSuffix>
+            )}
+          </StyledTitleRow>
+          {isDefined(note) && <StyledNote>{note}</StyledNote>}
+        </StyledHeaderLeft>
+        <StyledHeaderRight>
+          {isDefined(badge) && <StyledBadge>{badge}</StyledBadge>}
+          <Radio checked={selected} />
+        </StyledHeaderRight>
+      </StyledHeader>
+      {hasBody && <StyledBody>{children}</StyledBody>}
+    </StyledCard>
+  );
+};

packages/twenty-front/src/modules/onboarding/components/upgrade-free-trial/OnboardingTrialExtensionTag.tsx

@@ -0,0 +1,56 @@
+import { styled } from '@linaria/react';
+import { useLingui } from '@lingui/react/macro';
+import { IconCalendarEvent } from 'twenty-ui/icon';
+import { themeCssVariables, useTheme } from 'twenty-ui/theme-constants';
+
+const StyledTag = styled.div`
+  align-items: center;
+  background-color: ${themeCssVariables.color.green3};
+  border: 1px solid ${themeCssVariables.color.green4};
+  border-radius: ${themeCssVariables.border.radius.pill};
+  box-sizing: border-box;
+  color: ${themeCssVariables.color.green9};
+  display: flex;
+  gap: ${themeCssVariables.spacing[1]};
+  height: ${themeCssVariables.spacing[6]};
+  padding: 0 ${themeCssVariables.spacing[2]} 0
+    ${themeCssVariables.spacing['1.5']};
+`;
+
+const StyledPrefix = styled.span`
+  font-size: ${themeCssVariables.font.size.sm};
+  font-weight: ${themeCssVariables.font.weight.regular};
+`;
+
+const StyledDuration = styled.span`
+  font-size: ${themeCssVariables.font.size.md};
+  font-weight: ${themeCssVariables.font.weight.medium};
+`;
+
+const StyledSuffix = styled.span`
+  font-size: ${themeCssVariables.font.size.sm};
+  font-weight: ${themeCssVariables.font.weight.regular};
+`;
+
+type OnboardingTrialExtensionTagProps = {
+  duration: number;
+};
+
+export const OnboardingTrialExtensionTag = ({
+  duration,
+}: OnboardingTrialExtensionTagProps) => {
+  const { t } = useLingui();
+  const theme = useTheme();
+
+  return (
+    <StyledTag>
+      <IconCalendarEvent
+        size={theme.icon.size.md}
+        color={themeCssVariables.color.green9}
+      />
+      <StyledPrefix>{t`Extended`}</StyledPrefix>
+      <StyledDuration>{duration}</StyledDuration>
+      <StyledSuffix>{t`days trial`}</StyledSuffix>
+    </StyledTag>
+  );
+};

packages/twenty-front/src/modules/settings/billing/hooks/useHandleCheckoutSession.ts

@@ -30,22 +30,29 @@ export const useHandleCheckoutSession = ({
 
   const handleCheckoutSession = async () => {
     setIsSubmitting(true);
-    const { data } = await checkoutSession({
-      variables: {
-        recurringInterval,
-        successUrlPath,
-        plan,
-        requirePaymentMethod,
-      },
-    });
-    setIsSubmitting(false);
-    if (!data?.checkoutSession.url) {
+    try {
+      const { data } = await checkoutSession({
+        variables: {
+          recurringInterval,
+          successUrlPath,
+          plan,
+          requirePaymentMethod,
+        },
+      });
+      if (!data?.checkoutSession.url) {
+        enqueueErrorSnackBar({
+          message: t`Checkout session error. Please retry or contact Twenty team`,
+        });
+        return;
+      }
+      redirect(data.checkoutSession.url);
+    } catch {
       enqueueErrorSnackBar({
         message: t`Checkout session error. Please retry or contact Twenty team`,
       });
-      return;
+    } finally {
+      setIsSubmitting(false);
     }
-    redirect(data.checkoutSession.url);
   };
   return { isSubmitting, handleCheckoutSession };
 };