feat(clerk-js,types): Make payment method optional for free trials

It's flag-based.

Author: mauricioabreu

.changeset/bumpy-glasses-eat.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Remove the requirement to add a payment method when subscribing to free trials, depending on a flag

packages/clerk-js/sandbox/template.html

@@ -358,7 +358,7 @@
     <script
       type="text/javascript"
       src="/<%= htmlRspackPlugin.files.js[0] %>"
-      data-clerk-publishable-key="pk_test_dG91Y2hlZC1sYWR5YmlyZC0yMy5jbGVyay5hY2NvdW50cy5kZXYk"
+      data-clerk-publishable-key="pk_test_ZXZpZGVudC1lbGstMTQuY2xlcmsuYWNjb3VudHMubGNsY2xlcmsuY29tJA"
     ></script>
     <script
       type="text/javascript"

packages/clerk-js/src/core/resources/CommerceSettings.ts

@@ -8,6 +8,7 @@ import { BaseResource } from './internal';
 export class CommerceSettings extends BaseResource implements CommerceSettingsResource {
   billing: CommerceSettingsResource['billing'] = {
     stripePublishableKey: '',
+    freeTrialRequiresPaymentMethod: true,
     organization: {
       enabled: false,
       hasPaidPlans: false,
@@ -29,6 +30,7 @@ export class CommerceSettings extends BaseResource implements CommerceSettingsRe
     }
 
     this.billing.stripePublishableKey = data.billing.stripe_publishable_key || '';
+    this.billing.freeTrialRequiresPaymentMethod = data.billing.free_trial_requires_payment_method ?? true;
     this.billing.organization.enabled = data.billing.organization.enabled || false;
     this.billing.organization.hasPaidPlans = data.billing.organization.has_paid_plans || false;
     this.billing.user.enabled = data.billing.user.enabled || false;
@@ -41,6 +43,7 @@ export class CommerceSettings extends BaseResource implements CommerceSettingsRe
     return {
       billing: {
         stripe_publishable_key: this.billing.stripePublishableKey,
+        free_trial_requires_payment_method: this.billing.freeTrialRequiresPaymentMethod,
         organization: {
           enabled: this.billing.organization.enabled,
           has_paid_plans: this.billing.organization.hasPaidPlans,

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

@@ -12,7 +12,7 @@ import { Tooltip } from '@/ui/elements/Tooltip';
 import { handleError } from '@/ui/utils/errorHandler';
 
 import { DevOnly } from '../../common/DevOnly';
-import { useCheckoutContext, usePaymentMethods } from '../../contexts';
+import { useCheckoutContext, useEnvironment, usePaymentMethods } from '../../contexts';
 import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Spinner, Text } from '../../customizables';
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentMethod from '../PaymentMethods/AddPaymentMethod';
@@ -180,10 +180,13 @@ const useCheckoutMutations = () => {
       useTestCard: true,
     });
 
+  const subscribeWithoutPaymentMethod = () => confirmCheckout({});
+
   return {
     payWithExistingPaymentMethod,
     addPaymentMethodAndPay,
     payWithTestCard,
+    subscribeWithoutPaymentMethod,
   };
 };
 
@@ -214,12 +217,19 @@ const CheckoutFormElementsInternal = () => {
   const { checkout } = useCheckout();
   const { id, totals, isImmediatePlanChange, freeTrialEndsAt } = checkout;
   const { data: paymentMethods } = usePaymentMethods();
+  const environment = useEnvironment();
 
   const [paymentMethodSource, setPaymentMethodSource] = useState<PaymentMethodSource>(() =>
     paymentMethods.length > 0 || __BUILD_DISABLE_RHC__ ? 'existing' : 'new',
   );
 
-  const showPaymentMethods = isImmediatePlanChange && (totals.totalDueNow.amount > 0 || !!freeTrialEndsAt);
+  // 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));
 
   if (!id) {
     return null;
@@ -254,14 +264,19 @@ const CheckoutFormElementsInternal = () => {
         </>
       )}
 
-      {paymentMethodSource === 'existing' && (
+      {showPaymentMethods && paymentMethodSource === 'existing' && (
         <ExistingPaymentMethodForm
           paymentMethods={paymentMethods}
           totalDueNow={totals.totalDueNow}
         />
       )}
 
-      {__BUILD_DISABLE_RHC__ ? null : paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
+      {__BUILD_DISABLE_RHC__
+        ? null
+        : showPaymentMethods && paymentMethodSource === 'new' && <AddPaymentMethodForCheckout />}
+
+      {/* Show standalone subscribe button when payment methods are not needed */}
+      {!showPaymentMethods && isImmediatePlanChange && <StandaloneSubscribeButton />}
     </Col>
   );
 };
@@ -374,6 +389,7 @@ const ExistingPaymentMethodForm = withCardStateProvider(
     const submitLabel = useSubmitLabel();
     const { checkout } = useCheckout();
     const { paymentMethod, isImmediatePlanChange, freeTrialEndsAt } = checkout;
+    const environment = useEnvironment();
 
     const { payWithExistingPaymentMethod } = useCheckoutMutations();
     const card = useCardState();
@@ -395,7 +411,10 @@ const ExistingPaymentMethodForm = withCardStateProvider(
       });
     }, [paymentMethods]);
 
-    const showPaymentMethods = isImmediatePlanChange && (totalDueNow.amount > 0 || !!freeTrialEndsAt);
+    const showPaymentMethods =
+      isImmediatePlanChange &&
+      (totalDueNow.amount > 0 ||
+        (!!freeTrialEndsAt && environment.commerceSettings.billing.freeTrialRequiresPaymentMethod));
 
     return (
       <Form
@@ -462,3 +481,21 @@ const ExistingPaymentMethodForm = withCardStateProvider(
     );
   },
 );
+
+const StandaloneSubscribeButton = withCardStateProvider(() => {
+  const { subscribeWithoutPaymentMethod } = useCheckoutMutations();
+  const submitLabel = useSubmitLabel();
+  const card = useCardState();
+
+  return (
+    <Button
+      elementDescriptor={descriptors.formButtonPrimary}
+      onClick={subscribeWithoutPaymentMethod}
+      sx={{
+        width: '100%',
+      }}
+      isLoading={card.isLoading}
+      localizationKey={submitLabel}
+    />
+  );
+});

packages/types/src/commerceSettings.ts

@@ -5,6 +5,7 @@ import type { CommerceSettingsJSONSnapshot } from './snapshots';
 export interface CommerceSettingsJSON extends ClerkResourceJSON {
   billing: {
     stripe_publishable_key: string;
+    free_trial_requires_payment_method?: boolean;
     organization: {
       enabled: boolean;
       has_paid_plans: boolean;
@@ -19,6 +20,12 @@ export interface CommerceSettingsJSON extends ClerkResourceJSON {
 export interface CommerceSettingsResource extends ClerkResource {
   billing: {
     stripePublishableKey: string;
+    /**
+     * Whether payment methods are required when starting a free trial.
+     * When false, users can start free trials without providing payment methods.
+     * @default true
+     */
+    freeTrialRequiresPaymentMethod: boolean;
     organization: {
       enabled: boolean;
       hasPaidPlans: boolean;