fix: trust backend field everywhere

Author: mauricioabreu

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

@@ -331,7 +331,7 @@ export const CheckoutComplete = () => {
               localizationKey={
                 freeTrialEndsAt
                   ? localizationKeys('billing.checkout.title__trialSuccess')
-                  : totals.totalDueNow.amount > 0
+                  : needsPaymentMethod
                     ? localizationKeys('billing.checkout.title__paymentSuccessful')
                     : localizationKeys('billing.checkout.title__subscriptionSuccessful')
               }
@@ -386,7 +386,7 @@ export const CheckoutComplete = () => {
                 }),
               })}
               localizationKey={
-                totals.totalDueNow.amount > 0
+                needsPaymentMethod
                   ? localizationKeys('billing.checkout.description__paymentSuccessful')
                   : localizationKeys('billing.checkout.description__subscriptionSuccessful')
               }

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

@@ -219,15 +219,14 @@ const CheckoutFormElements = () => {
 
 const CheckoutFormElementsInternal = () => {
   const { checkout } = useCheckout();
-  const { id, totals, isImmediatePlanChange, freeTrialEndsAt, needsPaymentMethod } = checkout;
+  const { id, isImmediatePlanChange, needsPaymentMethod } = checkout;
   const { data: paymentMethods } = usePaymentMethods();
 
   const [paymentMethodSource, setPaymentMethodSource] = useState<PaymentMethodSource>(() =>
     paymentMethods.length > 0 || __BUILD_DISABLE_RHC__ ? 'existing' : 'new',
   );
 
-  const isFreeTrial = Boolean(freeTrialEndsAt);
-  const showTabs = isImmediatePlanChange && (totals.totalDueNow.amount > 0 || isFreeTrial);
+  const showTabs = isImmediatePlanChange && needsPaymentMethod && paymentMethods.length > 0;
 
   if (!id) {
     return null;
@@ -332,20 +331,25 @@ export const PayWithTestPaymentMethod = () => {
 
 const useSubmitLabel = () => {
   const { checkout } = useCheckout();
-  const { status, freeTrialEndsAt, totals } = checkout;
+  const { status, freeTrialEndsAt, totals, needsPaymentMethod } = checkout;
 
   if (status === 'needs_initialization') {
     throw new Error('Clerk: Invalid state');
   }
 
-  if (freeTrialEndsAt) {
-    return localizationKeys('billing.startFreeTrial');
+  // If payment method is needed, show payment-related labels
+  if (needsPaymentMethod) {
+    if (totals.totalDueNow.amount > 0) {
+      return localizationKeys('billing.pay', {
+        amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+      });
+    }
+    return localizationKeys('billing.subscribe');
   }
 
-  if (totals.totalDueNow.amount > 0) {
-    return localizationKeys('billing.pay', {
-      amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
-    });
+  // If no payment method needed and it's a trial, show free trial label
+  if (freeTrialEndsAt) {
+    return localizationKeys('billing.startFreeTrial');
   }
 
   return localizationKeys('billing.subscribe');

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

@@ -797,7 +797,8 @@ describe('Checkout', () => {
         const hiddenInput = baseElement.querySelector('input[name="payment_method_id"]');
         expect(hiddenInput).toHaveAttribute('value', 'pm_test_visa');
 
-        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
+        // Since needsPaymentMethod is true, should show Subscribe button, not Start free trial
+        expect(getByRole('button', { name: 'Subscribe' })).toBeInTheDocument();
       });
     });
 
@@ -1043,7 +1044,8 @@ describe('Checkout', () => {
       });
 
       await waitFor(() => {
-        expect(getByRole('button', { name: 'Start free trial' })).toBeInTheDocument();
+        // Since needsPaymentMethod is true, should show Subscribe button, not Start free trial
+        expect(getByRole('button', { name: 'Subscribe' })).toBeInTheDocument();
       });
     });
 
@@ -1128,13 +1130,15 @@ describe('Checkout', () => {
       await waitFor(async () => {
         expect(getByRole('heading', { name: 'Checkout' })).toBeVisible();
 
-        // Verify segmented control for payment method source is hidden
+        // Since needsPaymentMethod is true but no existing payment methods, should show payment collection UI directly
+        // Verify segmented control for payment method source is NOT visible (no choice to make)
         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();
+        // Should show Subscribe button, not Start free trial button
+        expect(getByRole('button', { name: 'Subscribe' })).toBeInTheDocument();
       });
     });