feat(clerk-js,localizations,shared,ui): Annual-only plans

.changeset/all-readers-dream.md

@@ -0,0 +1,9 @@
+---
+'@clerk/backend': minor
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add support for annual-only Billing plans.

packages/backend/src/api/resources/CommercePlan.ts

@@ -45,7 +45,7 @@ export class BillingPlan {
     /**
      * The monthly fee of the Plan.
      */
-    readonly fee: BillingMoneyAmount,
+    readonly fee: BillingMoneyAmount | null,
     /**
      * The annual fee of the Plan.
      */

packages/backend/src/api/resources/JSON.ts

@@ -854,7 +854,7 @@ export interface BillingPlanJSON extends ClerkResourceJSON {
   is_recurring: boolean;
   has_base_fee: boolean;
   publicly_visible: boolean;
-  fee: BillingMoneyAmountJSON;
+  fee: BillingMoneyAmountJSON | null;
   annual_fee: BillingMoneyAmountJSON | null;
   annual_monthly_fee: BillingMoneyAmountJSON | null;
   for_payer_type: 'org' | 'user';

packages/clerk-js/sandbox/scenarios/annual-only-plans.ts

@@ -0,0 +1,157 @@
+import {
+  clerkHandlers,
+  http,
+  HttpResponse,
+  EnvironmentService,
+  SessionService,
+  setClerkState,
+  type MockScenario,
+  UserService,
+} from '@clerk/msw';
+import type { BillingPlanJSON } from '@clerk/shared/types';
+
+export function AnnualOnlyPlans(): MockScenario {
+  const user = UserService.create();
+  const session = SessionService.create(user);
+  const money = (amount: number) => ({
+    amount,
+    amount_formatted: (amount / 100).toFixed(2),
+    currency: 'USD',
+    currency_symbol: '$',
+  });
+  const mockFeatures = [
+    {
+      object: 'feature' as const,
+      id: 'feature_custom_domains',
+      name: 'Custom domains',
+      description: 'Connect and manage branded domains.',
+      slug: 'custom-domains',
+      avatar_url: null,
+    },
+    {
+      object: 'feature' as const,
+      id: 'feature_saml_sso',
+      name: 'SAML SSO',
+      description: 'Single sign-on with enterprise identity providers.',
+      slug: 'saml-sso',
+      avatar_url: null,
+    },
+    {
+      object: 'feature' as const,
+      id: 'feature_audit_logs',
+      name: 'Audit logs',
+      description: 'Track account activity and security events.',
+      slug: 'audit-logs',
+      avatar_url: null,
+    },
+    {
+      object: 'feature' as const,
+      id: 'feature_priority_support',
+      name: 'Priority support',
+      description: 'Faster response times from the support team.',
+      slug: 'priority-support',
+      avatar_url: null,
+    },
+    {
+      object: 'feature' as const,
+      id: 'feature_rate_limit_boost',
+      name: 'Rate limit boost',
+      description: 'Higher API request thresholds for production traffic.',
+      slug: 'rate-limit-boost',
+      avatar_url: null,
+    },
+  ];
+
+  setClerkState({
+    environment: EnvironmentService.MULTI_SESSION,
+    session,
+    user,
+  });
+
+  const subscriptionHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/subscription', () => {
+    return HttpResponse.json({
+      response: {
+        data: {},
+      },
+    });
+  });
+
+  const paymentMethodsHandler = http.get('https://*.clerk.accounts.dev/v1/me/billing/payment_methods', () => {
+    return HttpResponse.json({
+      response: {
+        data: {},
+      },
+    });
+  });
+
+  const plansHandler = http.get('https://*.clerk.accounts.dev/v1/billing/plans', () => {
+    return HttpResponse.json({
+      data: [
+        {
+          object: 'commerce_plan',
+          id: 'plan_a_sbb',
+          name: 'Monthly-only',
+          fee: money(5000),
+          annual_fee: null,
+          annual_monthly_fee: null,
+          description: null,
+          is_default: false,
+          is_recurring: true,
+          has_base_fee: true,
+          for_payer_type: 'user',
+          publicly_visible: true,
+          slug: 'plan-a-sbb',
+          avatar_url: null,
+          features: mockFeatures,
+          free_trial_enabled: false,
+          free_trial_days: null,
+        },
+        {
+          object: 'commerce_plan',
+          id: 'plan_b_sbb',
+          name: 'Monthly & Annual',
+          fee: money(5000),
+          annual_fee: money(50000),
+          annual_monthly_fee: money(4167),
+          description: null,
+          is_default: false,
+          is_recurring: true,
+          has_base_fee: true,
+          for_payer_type: 'user',
+          publicly_visible: true,
+          slug: 'plan-b-sbb',
+          avatar_url: null,
+          features: mockFeatures,
+          free_trial_enabled: false,
+          free_trial_days: null,
+        },
+        {
+          object: 'commerce_plan',
+          id: 'plan_c_sbb',
+          name: 'Annual-only',
+          fee: null,
+          annual_fee: money(50000),
+          annual_monthly_fee: money(4167),
+          description: null,
+          is_default: false,
+          is_recurring: true,
+          has_base_fee: false,
+          for_payer_type: 'user',
+          publicly_visible: true,
+          slug: 'plan-c-sbb',
+          avatar_url: null,
+          features: mockFeatures,
+          free_trial_enabled: false,
+          free_trial_days: null,
+        },
+      ] as BillingPlanJSON[],
+    });
+  });
+
+  return {
+    description: 'PricingTable with annual-only billing plans',
+    handlers: [plansHandler, subscriptionHandler, paymentMethodsHandler, ...clerkHandlers],
+    initialState: { session, user },
+    name: 'annual-only-plans',
+  };
+}

packages/clerk-js/sandbox/scenarios/index.ts

@@ -1,2 +1,3 @@
 export { UserButtonSignedIn } from './user-button-signed-in';
 export { CheckoutAccountCredit } from './checkout-account-credit';
+export { AnnualOnlyPlans } from './annual-only-plans';

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

@@ -12,7 +12,7 @@ import { BaseResource, Feature } from './internal';
 export class BillingPlan extends BaseResource implements BillingPlanResource {
   id!: string;
   name!: string;
-  fee!: BillingMoneyAmount;
+  fee: BillingMoneyAmount | null = null;
   annualFee: BillingMoneyAmount | null = null;
   annualMonthlyFee: BillingMoneyAmount | null = null;
   description: string | null = null;
@@ -39,7 +39,7 @@ export class BillingPlan extends BaseResource implements BillingPlanResource {
 
     this.id = data.id;
     this.name = data.name;
-    this.fee = billingMoneyAmountFromJSON(data.fee);
+    this.fee = data.fee ? billingMoneyAmountFromJSON(data.fee) : null;
     this.annualFee = data.annual_fee ? billingMoneyAmountFromJSON(data.annual_fee) : null;
     this.annualMonthlyFee = data.annual_monthly_fee ? billingMoneyAmountFromJSON(data.annual_monthly_fee) : null;
     this.description = data.description;

packages/localizations/src/en-US.ts

@@ -69,6 +69,7 @@ export const enUS: LocalizationResource = {
     availableFeatures: 'Available features',
     billedAnnually: 'Billed annually',
     billedMonthlyOnly: 'Only billed monthly',
+    billedAnnuallyOnly: 'Only billed annually',
     cancelFreeTrial: 'Cancel free trial',
     cancelFreeTrialAccessUntil:
       "Your trial will stay active until {{ date | longDate('en-US') }}. After that, you'll lose access to trial features. You won't be charged.",

packages/msw/EnvironmentService.ts

@@ -32,13 +32,13 @@ const singleSessionEnvironment: EnvironmentPreset = {
     commerce_settings: {
       billing: {
         organization: {
-          enabled: false,
-          has_paid_plans: false,
+          enabled: true,
+          has_paid_plans: true,
         },
         stripe_publishable_key: '',
         user: {
-          enabled: false,
-          has_paid_plans: false,
+          enabled: true,
+          has_paid_plans: true,
         },
       },
       id: 'commerce_settings_1',

packages/shared/src/types/billing.ts

@@ -159,7 +159,7 @@ export interface BillingPlanResource extends ClerkResource {
   /**
    * The monthly price of the Plan.
    */
-  fee: BillingMoneyAmount;
+  fee: BillingMoneyAmount | null;
   /**
    * The annual price of the Plan or `null` if the Plan is not annual.
    */

packages/shared/src/types/json.ts

@@ -605,7 +605,7 @@ export interface BillingPlanJSON extends ClerkResourceJSON {
   object: 'commerce_plan';
   id: string;
   name: string;
-  fee: BillingMoneyAmountJSON;
+  fee: BillingMoneyAmountJSON | null;
   annual_fee: BillingMoneyAmountJSON | null;
   annual_monthly_fee: BillingMoneyAmountJSON | null;
   description: string | null;

packages/shared/src/types/localization.ts

@@ -193,6 +193,7 @@ export type __internal_LocalizationResource = {
     switchToAnnualWithAnnualPrice: LocalizationValue<'price' | 'currency'>;
     billedAnnually: LocalizationValue;
     billedMonthlyOnly: LocalizationValue;
+    billedAnnuallyOnly: LocalizationValue;
     cancelFreeTrial: LocalizationValue<'plan'>;
     cancelFreeTrialTitle: LocalizationValue<'plan'>;
     cancelFreeTrialAccessUntil: LocalizationValue<'plan' | 'date'>;

packages/ui/src/components/Plans/PlanDetails.tsx

@@ -226,8 +226,11 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
   }, [plan, planPeriod]);
 
   const feeFormatted = React.useMemo(() => {
-    return normalizeFormatted(fee.amountFormatted);
-  }, [fee.amountFormatted]);
+    if (!fee) {
+      return '';
+    }
+    return `${fee.currencySymbol}${normalizeFormatted(fee.amountFormatted)}`;
+  }, [fee]);
 
   return (
     <Box
@@ -306,7 +309,6 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
             variant='h1'
             colorScheme='body'
           >
-            {fee.currencySymbol}
             {feeFormatted}
           </Text>
           <Text
@@ -325,35 +327,73 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
         </>
       </Flex>
 
-      {plan.annualMonthlyFee ? (
-        <Box
-          elementDescriptor={descriptors.planDetailPeriodToggle}
-          sx={t => ({
-            display: 'flex',
-            marginTop: t.space.$3,
-          })}
-        >
-          <Switch
-            isChecked={planPeriod === 'annual'}
-            onChange={(checked: boolean) => setPlanPeriod(checked ? 'annual' : 'month')}
-            label={localizationKeys('billing.billedAnnually')}
-          />
-        </Box>
-      ) : (
-        <Text
-          elementDescriptor={descriptors.pricingTableCardFeePeriodNotice}
-          variant='caption'
-          colorScheme='secondary'
-          localizationKey={
-            plan.isDefault ? localizationKeys('billing.alwaysFree') : localizationKeys('billing.billedMonthlyOnly')
-          }
-          sx={t => ({
-            justifySelf: 'flex-start',
-            alignSelf: 'center',
-            marginTop: t.space.$3,
-          })}
-        />
-      )}
+      <PeriodToggle
+        plan={plan}
+        planPeriod={planPeriod}
+        setPlanPeriod={setPlanPeriod}
+      />
     </Box>
   );
 });
+
+const PeriodToggle = ({
+  plan,
+  planPeriod,
+  setPlanPeriod,
+}: {
+  plan: BillingPlanResource;
+  planPeriod: BillingSubscriptionPlanPeriod;
+  setPlanPeriod: (val: BillingSubscriptionPlanPeriod) => void;
+}) => {
+  if (plan.fee && plan.annualMonthlyFee) {
+    return (
+      <Box
+        elementDescriptor={descriptors.planDetailPeriodToggle}
+        sx={t => ({
+          display: 'flex',
+          marginTop: t.space.$3,
+        })}
+      >
+        <Switch
+          isChecked={planPeriod === 'annual'}
+          onChange={(checked: boolean) => setPlanPeriod(checked ? 'annual' : 'month')}
+          label={localizationKeys('billing.billedAnnually')}
+        />
+      </Box>
+    );
+  }
+
+  if (plan.annualMonthlyFee) {
+    return (
+      <Text
+        elementDescriptor={descriptors.pricingTableCardFeePeriodNotice}
+        variant='caption'
+        colorScheme='secondary'
+        localizationKey={
+          plan.isDefault ? localizationKeys('billing.alwaysFree') : localizationKeys('billing.billedAnnuallyOnly')
+        }
+        sx={t => ({
+          justifySelf: 'flex-start',
+          alignSelf: 'center',
+          marginTop: t.space.$3,
+        })}
+      />
+    );
+  }
+
+  return (
+    <Text
+      elementDescriptor={descriptors.pricingTableCardFeePeriodNotice}
+      variant='caption'
+      colorScheme='secondary'
+      localizationKey={
+        plan.isDefault ? localizationKeys('billing.alwaysFree') : localizationKeys('billing.billedMonthlyOnly')
+      }
+      sx={t => ({
+        justifySelf: 'flex-start',
+        alignSelf: 'center',
+        marginTop: t.space.$3,
+      })}
+    />
+  );
+};