fix(clerk-js): Update checkout to list available methods at trial checkout (#6608)

Author: panteliselef

.changeset/tall-worms-pull.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Allow end users to select payment methods during trial checkout.

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -192,7 +192,7 @@ const useCheckoutMutations = () => {
 
 const CheckoutFormElements = () => {
   const { checkout } = useCheckout();
-  const { id, totals } = checkout;
+  const { id, totals, freeTrialEndsAt } = checkout;
   const { data: paymentSources } = usePaymentMethods();
 
   const [paymentMethodSource, setPaymentMethodSource] = useState<PaymentMethodSource>(() =>
@@ -210,7 +210,7 @@ const CheckoutFormElements = () => {
       sx={t => ({ padding: t.space.$4 })}
     >
       {/* only show if there are payment sources and there is a total due now */}
-      {paymentSources.length > 0 && totals.totalDueNow.amount > 0 && (
+      {paymentSources.length > 0 && (totals.totalDueNow.amount > 0 || !!freeTrialEndsAt) && (
         <SegmentedControl.Root
           aria-label='Payment method source'
           value={paymentMethodSource}
@@ -370,7 +370,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
       });
     }, [paymentSources]);
 
-    const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+    const shouldDefaultBeUsed = totalDueNow.amount === 0 || !freeTrialEndsAt;
 
     return (
       <Form
@@ -381,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
           rowGap: t.space.$4,
         })}
       >
-        {isSchedulePayment ? (
+        {shouldDefaultBeUsed ? (
           <Select
             elementId='paymentSource'
             options={options}

packages/clerk-js/src/ui/components/Checkout/__tests__/Checkout.test.tsx

@@ -465,4 +465,140 @@ describe('Checkout', () => {
       expect(getByText('August 19, 2025')).toBeVisible();
     });
   });
+
+  it('renders existing payment sources during checkout confirmation', async () => {
+    const { wrapper, fixtures } = await createFixtures(f => {
+      f.withUser({ email_addresses: ['[email protected]'] });
+    });
+
+    fixtures.clerk.user?.getPaymentSources.mockResolvedValue({
+      data: [
+        {
+          id: 'pm_test_visa',
+          last4: '4242',
+          paymentMethod: 'card',
+          cardType: 'visa',
+          isDefault: true,
+          isRemovable: true,
+          status: 'active',
+          walletType: undefined,
+          remove: jest.fn(),
+          makeDefault: jest.fn(),
+          pathRoot: '/',
+          reload: jest.fn(),
+        },
+        {
+          id: 'pm_test_mastercard',
+          last4: '5555',
+          paymentMethod: 'card',
+          cardType: 'mastercard',
+          isDefault: false,
+          isRemovable: true,
+          status: 'active',
+          walletType: undefined,
+          remove: jest.fn(),
+          makeDefault: jest.fn(),
+          pathRoot: '/',
+          reload: jest.fn(),
+        },
+      ],
+      total_count: 2,
+    });
+
+    fixtures.clerk.billing.startCheckout.mockResolvedValue({
+      id: 'chk_trial_2',
+      status: 'needs_confirmation',
+      externalClientSecret: 'cs_test_trial_2',
+      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,
+      },
+      paymentSource: undefined,
+      confirm: jest.fn(),
+      freeTrialEndsAt: new Date('2025-08-19'),
+    } as any);
+
+    const { baseElement, getByText, getByRole, userEvent } = render(
+      <Drawer.Root
+        open
+        onOpenChange={() => {}}
+      >
+        <Checkout
+          planId='plan_with_payment_sources'
+          planPeriod='month'
+        />
+      </Drawer.Root>,
+      { wrapper },
+    );
+
+    await waitFor(async () => {
+      // Verify checkout title is displayed
+      expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+      // Verify segmented control for payment method source is rendered
+      const paymentMethodsButton = getByText('Payment Methods');
+      expect(paymentMethodsButton).toBeVisible();
+
+      const addPaymentMethodButton = getByText('Add payment method');
+      expect(addPaymentMethodButton).toBeVisible();
+
+      await userEvent.click(paymentMethodsButton);
+    });
+
+    await waitFor(() => {
+      const visaPaymentSource = getByText('visa');
+      expect(visaPaymentSource).toBeVisible();
+
+      const last4Digits = getByText('⋯ 4242');
+      expect(last4Digits).toBeVisible();
+
+      // Verify the default badge is shown for the first payment source
+      const defaultBadge = getByText('Default');
+      expect(defaultBadge).toBeVisible();
+
+      // Verify the hidden input contains the correct payment source id
+      const hiddenInput = baseElement.querySelector('input[name="payment_source_id"]');
+      expect(hiddenInput).toHaveAttribute('value', 'pm_test_visa');
+    });
+  });
 });