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/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

@@ -1,5 +1,5 @@
 import { __experimental_useCheckout as useCheckout } from '@clerk/shared/react';
-import type { BillingMoneyAmount, BillingPaymentMethodResource, ConfirmCheckoutParams } from '@clerk/types';
+import type { BillingPaymentMethodResource, ConfirmCheckoutParams } from '@clerk/types';
 import { useMemo, useState } from 'react';
 
 import { Card } from '@/ui/elements/Card';
@@ -13,6 +13,7 @@ import { handleError } from '@/ui/utils/errorHandler';
 
 import { DevOnly } from '../../common/DevOnly';
 import { useCheckoutContext, usePaymentMethods } from '../../contexts';
+import { useShowPaymentMethods } from '../../hooks';
 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 +181,13 @@ const useCheckoutMutations = () => {
       useTestCard: true,
     });
 
+  const subscribeWithoutPaymentMethod = () => confirmCheckout({});
+
   return {
     payWithExistingPaymentMethod,
     addPaymentMethodAndPay,
     payWithTestCard,
+    subscribeWithoutPaymentMethod,
   };
 };
 
@@ -212,14 +216,14 @@ const CheckoutFormElements = () => {
 
 const CheckoutFormElementsInternal = () => {
   const { checkout } = useCheckout();
-  const { id, totals, isImmediatePlanChange, freeTrialEndsAt } = checkout;
+  const { id, isImmediatePlanChange } = checkout;
   const { data: paymentMethods } = usePaymentMethods();
 
   const [paymentMethodSource, setPaymentMethodSource] = useState<PaymentMethodSource>(() =>
     paymentMethods.length > 0 || __BUILD_DISABLE_RHC__ ? 'existing' : 'new',
   );
 
-  const showPaymentMethods = isImmediatePlanChange && (totals.totalDueNow.amount > 0 || !!freeTrialEndsAt);
+  const showPaymentMethods = useShowPaymentMethods();
 
   if (!id) {
     return null;
@@ -254,14 +258,16 @@ const CheckoutFormElementsInternal = () => {
         </>
       )}
 
-      {paymentMethodSource === 'existing' && (
-        <ExistingPaymentMethodForm
-          paymentMethods={paymentMethods}
-          totalDueNow={totals.totalDueNow}
-        />
+      {showPaymentMethods && paymentMethodSource === 'existing' && (
+        <ExistingPaymentMethodForm paymentMethods={paymentMethods} />
       )}
 
-      {__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>
   );
 };
@@ -364,16 +370,10 @@ const AddPaymentMethodForCheckout = withCardStateProvider(() => {
 });
 
 const ExistingPaymentMethodForm = withCardStateProvider(
-  ({
-    totalDueNow,
-    paymentMethods,
-  }: {
-    totalDueNow: BillingMoneyAmount;
-    paymentMethods: BillingPaymentMethodResource[];
-  }) => {
+  ({ paymentMethods }: { paymentMethods: BillingPaymentMethodResource[] }) => {
     const submitLabel = useSubmitLabel();
     const { checkout } = useCheckout();
-    const { paymentMethod, isImmediatePlanChange, freeTrialEndsAt } = checkout;
+    const { paymentMethod } = checkout;
 
     const { payWithExistingPaymentMethod } = useCheckoutMutations();
     const card = useCardState();
@@ -395,7 +395,7 @@ const ExistingPaymentMethodForm = withCardStateProvider(
       });
     }, [paymentMethods]);
 
-    const showPaymentMethods = isImmediatePlanChange && (totalDueNow.amount > 0 || !!freeTrialEndsAt);
+    const showPaymentMethods = useShowPaymentMethods();
 
     return (
       <Form
@@ -462,3 +462,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/clerk-js/src/ui/hooks/index.ts

@@ -16,4 +16,5 @@ export * from './usePrefersReducedMotion';
 export * from './useSafeState';
 export * from './useScrollLock';
 export * from './useSearchInput';
+export * from './useShowPaymentMethods';
 export * from './useWindowEventListener';

packages/clerk-js/src/ui/hooks/useShowPaymentMethods.ts

@@ -0,0 +1,30 @@
+import { __experimental_useCheckout as useCheckout } from '@clerk/shared/react';
+
+import { useEnvironment } from '../contexts';
+
+/**
+ * Custom hook that determines whether payment methods should be shown in checkout flows.
+ *
+ * Payment methods are shown when:
+ * 1. It's an immediate plan change (not a downgrade)
+ * 2. Either there's an amount due now OR it's a free trial that requires payment method
+ *
+ * @returns boolean indicating whether payment methods should be displayed
+ */
+export const useShowPaymentMethods = (): boolean => {
+  const { checkout } = useCheckout();
+  const environment = useEnvironment();
+
+  const { isImmediatePlanChange, totals, freeTrialEndsAt } = checkout;
+
+  // Return false if checkout data is not loaded yet
+  if (!isImmediatePlanChange || !totals) {
+    return false;
+  }
+
+  return (
+    isImmediatePlanChange &&
+    (totals.totalDueNow.amount > 0 ||
+      (!!freeTrialEndsAt && environment.commerceSettings.billing.freeTrialRequiresPaymentMethod))
+  );
+};

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;