From 69ee656da0639f13c0c7cd926d2424409ac9093b Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Thu, 23 Oct 2025 21:48:16 -0700
Subject: [PATCH 1/4] wip

---
 .../src/ui/components/Checkout/CheckoutForm.tsx      | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
index 7b8e8ae9416..15b5cd3fbd0 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -228,6 +228,12 @@ const CheckoutFormElementsInternal = () => {
     (totals.totalDueNow.amount > 0 ||
       (!!freeTrialEndsAt && environment.commerceSettings.billing.freeTrialRequiresPaymentMethod));
 
+  // Only show the standalone free trial button when it's a free trial that does not
+  // require a payment method. Hiding payment methods (e.g. downgrade) should not imply
+  // showing the free trial button.
+  const showFreeTrialButton =
+    !showPaymentMethods && !!freeTrialEndsAt && !environment.commerceSettings.billing.freeTrialRequiresPaymentMethod;
+
   if (!id) {
     return null;
   }
@@ -261,18 +267,20 @@ const CheckoutFormElementsInternal = () => {
         </>
       )}
 
-      {showPaymentMethods && paymentMethodSource === 'existing' && (
+      {paymentMethods.length > 0 && (paymentMethodSource === 'existing' || !showPaymentMethods) && (
         <ExistingPaymentMethodForm
           paymentMethods={paymentMethods}
           totalDueNow={totals.totalDueNow}
         />
       )}
 
+      {/* {__BUILD_DISABLE_RHC__ ? null : paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />} */}
+
       {__BUILD_DISABLE_RHC__
         ? null
         : showPaymentMethods && paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
 
-      {!showPaymentMethods && <FreeTrialButton />}
+      {showFreeTrialButton && <FreeTrialButton />}
     </Col>
   );
 };

From 7402cdd90c785e9a7e00cfe8d6516645ee94e6d9 Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Thu, 23 Oct 2025 21:48:23 -0700
Subject: [PATCH 2/4] Revert "wip"

This reverts commit 69ee656da0639f13c0c7cd926d2424409ac9093b.
---
 .../src/ui/components/Checkout/CheckoutForm.tsx      | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
index 15b5cd3fbd0..7b8e8ae9416 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -228,12 +228,6 @@ const CheckoutFormElementsInternal = () => {
     (totals.totalDueNow.amount > 0 ||
       (!!freeTrialEndsAt && environment.commerceSettings.billing.freeTrialRequiresPaymentMethod));
 
-  // Only show the standalone free trial button when it's a free trial that does not
-  // require a payment method. Hiding payment methods (e.g. downgrade) should not imply
-  // showing the free trial button.
-  const showFreeTrialButton =
-    !showPaymentMethods && !!freeTrialEndsAt && !environment.commerceSettings.billing.freeTrialRequiresPaymentMethod;
-
   if (!id) {
     return null;
   }
@@ -267,20 +261,18 @@ const CheckoutFormElementsInternal = () => {
         </>
       )}
 
-      {paymentMethods.length > 0 && (paymentMethodSource === 'existing' || !showPaymentMethods) && (
+      {showPaymentMethods && paymentMethodSource === 'existing' && (
         <ExistingPaymentMethodForm
           paymentMethods={paymentMethods}
           totalDueNow={totals.totalDueNow}
         />
       )}
 
-      {/* {__BUILD_DISABLE_RHC__ ? null : paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />} */}
-
       {__BUILD_DISABLE_RHC__
         ? null
         : showPaymentMethods && paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
 
-      {showFreeTrialButton && <FreeTrialButton />}
+      {!showPaymentMethods && <FreeTrialButton />}
     </Col>
   );
 };

From 3ca7cca0559e1f49d6ab5819c29312cc417326cd Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Thu, 23 Oct 2025 22:59:07 -0700
Subject: [PATCH 3/4] fix and write tests

---
 packages/clerk-js/src/test/fixture-helpers.ts |  23 +-
 .../ui/components/Checkout/CheckoutForm.tsx   | 132 +++---
 .../Checkout/__tests__/Checkout.test.tsx      | 403 +++++++++++++++++-
 3 files changed, 475 insertions(+), 83 deletions(-)

diff --git a/packages/clerk-js/src/test/fixture-helpers.ts b/packages/clerk-js/src/test/fixture-helpers.ts
index 143e7e6a7c3..816996d289b 100644
--- a/packages/clerk-js/src/test/fixture-helpers.ts
+++ b/packages/clerk-js/src/test/fixture-helpers.ts
@@ -362,11 +362,24 @@ const createOrganizationSettingsFixtureHelpers = (environment: EnvironmentJSON)
 
 const createBillingSettingsFixtureHelpers = (environment: EnvironmentJSON) => {
   const os = environment.commerce_settings.billing;
-  const withBilling = () => {
-    os.user.enabled = true;
-    os.user.has_paid_plans = true;
-    os.organization.enabled = true;
-    os.organization.has_paid_plans = true;
+  const withBilling = ({
+    userEnabled = true,
+    userHasPaidPlans = true,
+    organizationEnabled = true,
+    organizationHasPaidPlans = true,
+    freeTrialRequiresPaymentMethod = true,
+  }: {
+    userEnabled?: boolean;
+    userHasPaidPlans?: boolean;
+    organizationEnabled?: boolean;
+    organizationHasPaidPlans?: boolean;
+    freeTrialRequiresPaymentMethod?: boolean;
+  } = {}) => {
+    os.user.enabled = userEnabled;
+    os.user.has_paid_plans = userHasPaidPlans;
+    os.organization.enabled = organizationEnabled;
+    os.organization.has_paid_plans = organizationHasPaidPlans;
+    os.free_trial_requires_payment_method = freeTrialRequiresPaymentMethod;
   };
 
   return { withBilling };
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
index 7b8e8ae9416..4c240fb7637 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -15,6 +15,7 @@ import { DevOnly } from '../../common/DevOnly';
 import { useCheckoutContext, useEnvironment, usePaymentMethods } from '../../contexts';
 import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Spinner, Text } from '../../customizables';
 import { ChevronUpDown, InformationCircle } from '../../icons';
+import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
 import * as AddPaymentMethod from '../PaymentMethods/AddPaymentMethod';
 import { PaymentMethodRow } from '../PaymentMethods/PaymentMethodRow';
 import { SubscriptionBadge } from '../Subscriptions/badge';
@@ -138,7 +139,7 @@ export const CheckoutForm = withCardStateProvider(() => {
 });
 
 const useCheckoutMutations = () => {
-  const { for: _for, onSubscriptionComplete } = useCheckoutContext();
+  const { onSubscriptionComplete } = useCheckoutContext();
   const { checkout } = useCheckout();
   const { id, confirm } = checkout;
   const card = useCardState();
@@ -172,6 +173,11 @@ const useCheckoutMutations = () => {
     });
   };
 
+  const payWithoutPaymentMethod = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    return confirmCheckout({});
+  };
+
   const addPaymentMethodAndPay = (ctx: { gateway: 'stripe'; paymentToken: string }) => confirmCheckout(ctx);
 
   const payWithTestCard = () =>
@@ -184,6 +190,7 @@ const useCheckoutMutations = () => {
     payWithExistingPaymentMethod,
     addPaymentMethodAndPay,
     payWithTestCard,
+    payWithoutPaymentMethod,
   };
 };
 
@@ -220,13 +227,9 @@ const CheckoutFormElementsInternal = () => {
     paymentMethods.length > 0 || __BUILD_DISABLE_RHC__ ? 'existing' : 'new',
   );
 
-  // Check if payment methods should be shown based on:
-  // 1. Immediate plan change (not a downgrade)
-  // 2. Either there's an amount due now OR it's a free trial that requires payment method
-  const showPaymentMethods =
-    isImmediatePlanChange &&
-    (totals.totalDueNow.amount > 0 ||
-      (!!freeTrialEndsAt && environment.commerceSettings.billing.freeTrialRequiresPaymentMethod));
+  const isFreeTrial = Boolean(freeTrialEndsAt);
+  const showTabs = isImmediatePlanChange && (totals.totalDueNow.amount > 0 || isFreeTrial);
+  const needsPaymentMethod = !(isFreeTrial && !environment.commerceSettings.billing.freeTrialRequiresPaymentMethod);
 
   if (!id) {
     return null;
@@ -240,7 +243,7 @@ const CheckoutFormElementsInternal = () => {
     >
       {__BUILD_DISABLE_RHC__ ? null : (
         <>
-          {paymentMethods.length > 0 && showPaymentMethods && (
+          {paymentMethods.length > 0 && showTabs && needsPaymentMethod && (
             <SegmentedControl.Root
               aria-label='Payment method source'
               value={paymentMethodSource}
@@ -261,18 +264,17 @@ const CheckoutFormElementsInternal = () => {
         </>
       )}
 
-      {showPaymentMethods && paymentMethodSource === 'existing' && (
-        <ExistingPaymentMethodForm
-          paymentMethods={paymentMethods}
-          totalDueNow={totals.totalDueNow}
-        />
-      )}
-
-      {__BUILD_DISABLE_RHC__
-        ? null
-        : showPaymentMethods && paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
+      {paymentMethodSource === 'existing' &&
+        (needsPaymentMethod ? (
+          <ExistingPaymentMethodForm
+            paymentMethods={paymentMethods}
+            totalDueNow={totals.totalDueNow}
+          />
+        ) : (
+          <FreeTrialButton />
+        ))}
 
-      {!showPaymentMethods && <FreeTrialButton />}
+      {__BUILD_DISABLE_RHC__ ? null : paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
     </Col>
   );
 };
@@ -356,52 +358,17 @@ const useSubmitLabel = () => {
 };
 
 const FreeTrialButton = withCardStateProvider(() => {
-  const { for: _for, onSubscriptionComplete } = useCheckoutContext();
-  const submitLabel = useSubmitLabel();
+  const { for: _for } = useCheckoutContext();
+  const { payWithoutPaymentMethod } = useCheckoutMutations();
   const card = useCardState();
-  const { checkout } = useCheckout();
-
-  const handleFreeTrialStart = async () => {
-    card.setLoading();
-    card.setError(undefined);
-
-    try {
-      // For free trials without payment method requirement, we can confirm without payment details
-      const { data, error } = await checkout.confirm({});
-
-      if (error) {
-        handleError(error, [], card.setError);
-      } else if (data) {
-        onSubscriptionComplete?.();
-      }
-    } catch (error) {
-      handleError(error, [], card.setError);
-    } finally {
-      card.setIdle();
-    }
-  };
 
   return (
     <Form
-      sx={t => ({
-        display: 'flex',
-        flexDirection: 'column',
-        rowGap: t.space.$4,
-      })}
+      onSubmit={payWithoutPaymentMethod}
+      sx={formProps}
     >
       <Card.Alert>{card.error}</Card.Alert>
-      <Button
-        type='button'
-        colorScheme='primary'
-        size='sm'
-        textVariant={'buttonLarge'}
-        sx={{
-          width: '100%',
-        }}
-        isLoading={card.isLoading}
-        localizationKey={submitLabel}
-        onClick={handleFreeTrialStart}
-      />
+      <CheckoutSubmitButton />
     </Form>
   );
 });
@@ -425,6 +392,32 @@ const AddPaymentMethodForCheckout = withCardStateProvider(() => {
   );
 });
 
+const CheckoutSubmitButton = (props: PropsOfComponent<typeof Button>) => {
+  const card = useCardState();
+  const submitLabel = useSubmitLabel();
+
+  return (
+    <Button
+      type='submit'
+      colorScheme='primary'
+      size='sm'
+      textVariant={'buttonLarge'}
+      sx={{
+        width: '100%',
+      }}
+      isLoading={card.isLoading}
+      localizationKey={submitLabel}
+      {...props}
+    />
+  );
+};
+
+const formProps: ThemableCssProp = t => ({
+  display: 'flex',
+  flexDirection: 'column',
+  rowGap: t.space.$4,
+});
+
 const ExistingPaymentMethodForm = withCardStateProvider(
   ({
     totalDueNow,
@@ -433,7 +426,6 @@ const ExistingPaymentMethodForm = withCardStateProvider(
     totalDueNow: BillingMoneyAmount;
     paymentMethods: BillingPaymentMethodResource[];
   }) => {
-    const submitLabel = useSubmitLabel();
     const { checkout } = useCheckout();
     const { paymentMethod, isImmediatePlanChange, freeTrialEndsAt } = checkout;
     const environment = useEnvironment();
@@ -466,11 +458,7 @@ const ExistingPaymentMethodForm = withCardStateProvider(
     return (
       <Form
         onSubmit={payWithExistingPaymentMethod}
-        sx={t => ({
-          display: 'flex',
-          flexDirection: 'column',
-          rowGap: t.space.$4,
-        })}
+        sx={formProps}
       >
         {showPaymentMethods ? (
           <Select
@@ -513,17 +501,7 @@ const ExistingPaymentMethodForm = withCardStateProvider(
           />
         )}
         <Card.Alert>{card.error}</Card.Alert>
-        <Button
-          type='submit'
-          colorScheme='primary'
-          size='sm'
-          textVariant={'buttonLarge'}
-          sx={{
-            width: '100%',
-          }}
-          isLoading={card.isLoading}
-          localizationKey={submitLabel}
-        />
+        <CheckoutSubmitButton />
       </Form>
     );
   },
diff --git a/packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx b/packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx
index ce67f1dbf29..e4ef20dc556 100644
--- a/packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx
@@ -931,7 +931,408 @@ describe('Checkout', () => {
         const hiddenInput = baseElement.querySelector('input[name="payment_method_id"]');
         expect(hiddenInput).toHaveAttribute('value', 'pm_test_visa');
 
-        expect(getByRole('button', { name: 'Pay $10.00' })).toBeInTheDocument();
+        const payButton = getByRole('button', { name: 'Pay $10.00' });
+        expect(payButton).toBeInTheDocument();
+      });
+    });
+
+    it('renders free trial submit in Add payment method tab for free trial', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withUser({ email_addresses: ['test@clerk.com'] });
+        f.withBilling();
+      });
+
+      fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+        data: [
+          {
+            id: 'pm_test_visa',
+            last4: '4242',
+            paymentType: 'card',
+            cardType: 'visa',
+            isDefault: true,
+            isRemovable: true,
+            status: 'active',
+            walletType: undefined,
+            remove: vi.fn(),
+            makeDefault: vi.fn(),
+            pathRoot: '/',
+            reload: vi.fn(),
+          },
+        ],
+        total_count: 1,
+      });
+
+      fixtures.clerk.billing.startCheckout.mockResolvedValue({
+        id: 'chk_trial_tabs_new',
+        status: 'needs_confirmation',
+        externalClientSecret: 'cs_test_trial_tabs_new',
+        externalGatewayId: 'gw_test',
+        totals: {
+          subtotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          grandTotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          taxTotal: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          credit: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          pastDue: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          totalDueNow: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+        },
+        isImmediatePlanChange: true,
+        planPeriod: 'month',
+        plan: {
+          id: 'plan_trial',
+          name: 'Pro',
+          description: 'Pro plan',
+          features: [],
+          fee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualFee: {
+            amount: 12000,
+            amountFormatted: '120.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualMonthlyFee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          slug: 'pro',
+          avatarUrl: '',
+          publiclyVisible: true,
+          isDefault: true,
+          isRecurring: true,
+          hasBaseFee: false,
+          forPayerType: 'user',
+          freeTrialDays: 7,
+          freeTrialEnabled: true,
+        },
+        paymentMethod: undefined,
+        confirm: vi.fn(),
+        freeTrialEndsAt: new Date('2025-08-19'),
+      } as any);
+
+      const { getByText, getByRole, userEvent } = render(
+        <Drawer.Root
+          open
+          onOpenChange={() => {}}
+        >
+          <Checkout
+            planId='plan_with_payment_methods_free_trial_new'
+            planPeriod='month'
+          />
+        </Drawer.Root>,
+        { wrapper },
+      );
+
+      await waitFor(async () => {
+        expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
+        const addPaymentMethodButton = getByText('Add payment method');
+        expect(addPaymentMethodButton).toBeVisible();
+        await userEvent.click(addPaymentMethodButton);
+      });
+
+      await waitFor(() => {
+        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
+      });
+    });
+
+    it('prompts for adding payment method for free trial if none exists and requires payment method', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withUser({ email_addresses: ['test@clerk.com'] });
+        f.withBilling({ freeTrialRequiresPaymentMethod: true });
+      });
+
+      fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+        data: [],
+        total_count: 0,
+      });
+
+      fixtures.clerk.billing.startCheckout.mockResolvedValue({
+        id: 'chk_trial_tabs_new',
+        status: 'needs_confirmation',
+        externalClientSecret: 'cs_test_trial_tabs_new',
+        externalGatewayId: 'gw_test',
+        totals: {
+          subtotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          grandTotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          taxTotal: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          credit: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          pastDue: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          totalDueNow: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+        },
+        isImmediatePlanChange: true,
+        planPeriod: 'month',
+        plan: {
+          id: 'plan_trial',
+          name: 'Pro',
+          description: 'Pro plan',
+          features: [],
+          fee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualFee: {
+            amount: 12000,
+            amountFormatted: '120.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualMonthlyFee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          slug: 'pro',
+          avatarUrl: '',
+          publiclyVisible: true,
+          isDefault: true,
+          isRecurring: true,
+          hasBaseFee: false,
+          forPayerType: 'user',
+          freeTrialDays: 7,
+          freeTrialEnabled: true,
+        },
+        paymentMethod: undefined,
+        confirm: vi.fn(),
+        freeTrialEndsAt: new Date('2025-08-19'),
+      } as any);
+
+      const { queryByText, getByRole } = render(
+        <Drawer.Root
+          open
+          onOpenChange={() => {}}
+        >
+          <Checkout
+            planId='plan_with_payment_methods_free_trial_new'
+            planPeriod='month'
+          />
+        </Drawer.Root>,
+        { wrapper },
+      );
+
+      await waitFor(async () => {
+        expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+        // Verify segmented control for payment method source is hidden
+        const paymentMethodsButton = queryByText('Payment Methods');
+        expect(paymentMethodsButton).toBeNull();
+        const addPaymentMethodButton = queryByText('Add payment method');
+        expect(addPaymentMethodButton).toBeNull();
+
+        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
+      });
+    });
+
+    it('does not prompt payment methods for free trial when not required', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withUser({ email_addresses: ['test@clerk.com'] });
+        f.withBilling({ freeTrialRequiresPaymentMethod: false });
+      });
+
+      fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+        data: [],
+        total_count: 0,
+      });
+
+      fixtures.clerk.billing.startCheckout.mockResolvedValue({
+        id: 'chk_trial_tabs_new',
+        status: 'needs_confirmation',
+        externalClientSecret: 'cs_test_trial_tabs_new',
+        externalGatewayId: 'gw_test',
+        totals: {
+          subtotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          grandTotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          taxTotal: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          credit: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          pastDue: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          totalDueNow: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+        },
+        isImmediatePlanChange: true,
+        planPeriod: 'month',
+        plan: {
+          id: 'plan_trial',
+          name: 'Pro',
+          description: 'Pro plan',
+          features: [],
+          fee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualFee: {
+            amount: 12000,
+            amountFormatted: '120.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualMonthlyFee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          slug: 'pro',
+          avatarUrl: '',
+          publiclyVisible: true,
+          isDefault: true,
+          isRecurring: true,
+          hasBaseFee: false,
+          forPayerType: 'user',
+          freeTrialDays: 7,
+          freeTrialEnabled: true,
+        },
+        paymentMethod: undefined,
+        confirm: vi.fn(),
+        freeTrialEndsAt: new Date('2025-08-19'),
+      } as any);
+
+      const { queryByText, getByRole, baseElement } = render(
+        <Drawer.Root
+          open
+          onOpenChange={() => {}}
+        >
+          <Checkout
+            planId='plan_with_payment_methods_free_trial_new'
+            planPeriod='month'
+          />
+        </Drawer.Root>,
+        { wrapper },
+      );
+
+      await waitFor(async () => {
+        expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+        // Verify segmented control for payment method source is hidden
+        const paymentMethodsButton = queryByText('Payment Methods');
+        expect(paymentMethodsButton).toBeNull();
+        const addPaymentMethodButton = queryByText('Add payment method');
+        expect(addPaymentMethodButton).toBeNull();
+
+        expect(queryByText('Development mode')).toBeNull();
+
+        // Verify the hidden input is not rendered
+        const hiddenInput = baseElement.querySelector('input[name="payment_method_id"]');
+        expect(hiddenInput).toBeNull();
+
+        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
+      });
+    });
+
+    it('does not prompt payment methods for free trial when not required, even with stored payment methods', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withUser({ email_addresses: ['test@clerk.com'] });
+        f.withBilling({ freeTrialRequiresPaymentMethod: false });
+      });
+
+      fixtures.clerk.user?.getPaymentMethods.mockResolvedValue({
+        data: [
+          {
+            id: 'pm_test_visa',
+            last4: '4242',
+            paymentType: 'card',
+            cardType: 'visa',
+            isDefault: true,
+          },
+        ],
+        total_count: 1,
+      });
+
+      fixtures.clerk.billing.startCheckout.mockResolvedValue({
+        id: 'chk_trial_tabs_new',
+        status: 'needs_confirmation',
+        externalClientSecret: 'cs_test_trial_tabs_new',
+        externalGatewayId: 'gw_test',
+        totals: {
+          subtotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          grandTotal: { amount: 1000, amountFormatted: '10.00', currency: 'USD', currencySymbol: '$' },
+          taxTotal: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          credit: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          pastDue: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+          totalDueNow: { amount: 0, amountFormatted: '0.00', currency: 'USD', currencySymbol: '$' },
+        },
+        isImmediatePlanChange: true,
+        planPeriod: 'month',
+        plan: {
+          id: 'plan_trial',
+          name: 'Pro',
+          description: 'Pro plan',
+          features: [],
+          fee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualFee: {
+            amount: 12000,
+            amountFormatted: '120.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          annualMonthlyFee: {
+            amount: 1000,
+            amountFormatted: '10.00',
+            currency: 'USD',
+            currencySymbol: '$',
+          },
+          slug: 'pro',
+          avatarUrl: '',
+          publiclyVisible: true,
+          isDefault: true,
+          isRecurring: true,
+          hasBaseFee: false,
+          forPayerType: 'user',
+          freeTrialDays: 7,
+          freeTrialEnabled: true,
+        },
+        paymentMethod: undefined,
+        confirm: vi.fn(),
+        freeTrialEndsAt: new Date('2025-08-19'),
+      } as any);
+
+      const { queryByText, getByRole, baseElement } = render(
+        <Drawer.Root
+          open
+          onOpenChange={() => {}}
+        >
+          <Checkout
+            planId='plan_with_payment_methods_free_trial_new'
+            planPeriod='month'
+          />
+        </Drawer.Root>,
+        { wrapper },
+      );
+
+      await waitFor(async () => {
+        expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+        // Verify segmented control for payment method source is hidden
+        const paymentMethodsButton = queryByText('Payment Methods');
+        expect(paymentMethodsButton).toBeNull();
+        const addPaymentMethodButton = queryByText('Add payment method');
+        expect(addPaymentMethodButton).toBeNull();
+
+        expect(queryByText('Development mode')).toBeNull();
+
+        const visaPaymentMethod = queryByText('visa');
+        expect(visaPaymentMethod).toBeNull();
+
+        const last4Digits = queryByText('⋯ 4242');
+        expect(last4Digits).toBeNull();
+
+        // Verify the hidden input is not rendered
+        const hiddenInput = baseElement.querySelector('input[name="payment_method_id"]');
+        expect(hiddenInput).toBeNull();
+
+        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
       });
     });
 

From 68a6c12e145e40e5fc8c92acb8b6bfb2bde73d34 Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Thu, 23 Oct 2025 23:06:08 -0700
Subject: [PATCH 4/4] changeset

---
 .changeset/pretty-garlics-sing.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/pretty-garlics-sing.md

diff --git a/.changeset/pretty-garlics-sing.md b/.changeset/pretty-garlics-sing.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/pretty-garlics-sing.md
@@ -0,0 +1,2 @@
+---
+---