clerk · aeliox · Apr 28, 2025 · Apr 28, 2025 · Apr 28, 2025 · Apr 28, 2025
diff --git a/.changeset/cruel-berries-flow.md b/.changeset/cruel-berries-flow.md
@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Renames all instances of `SubscriptionDetails` to `PlanDetails` to better reflect the capabilities, use cases, and params of the component.
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -16,8 +16,8 @@ import { allSettled, handleValueOrFn, noop } from '@clerk/shared/utils';
 import type {
   __experimental_CheckoutProps,
   __experimental_CommerceNamespace,
+  __experimental_PlanDetailsProps,
   __experimental_PricingTableProps,
-  __experimental_SubscriptionDetailsProps,
   __internal_ComponentNavigationContext,
   __internal_UserVerificationModalProps,
   AuthenticateWithCoinbaseWalletParams,
@@ -564,24 +564,24 @@ export class Clerk implements ClerkInterface {
     void this.#componentControls.ensureMounted().then(controls => controls.closeDrawer('checkout'));
   };
 
-  public __internal_openSubscriptionDetails = (props?: __experimental_SubscriptionDetailsProps): void => {
+  public __internal_openPlanDetails = (props?: __experimental_PlanDetailsProps): void => {
     this.assertComponentsReady(this.#componentControls);
     if (disabledBillingFeature(this, this.environment)) {
       if (this.#instanceType === 'development') {
-        throw new ClerkRuntimeError(warnings.cannotRenderAnyCommerceComponent('SubscriptionDetails'), {
+        throw new ClerkRuntimeError(warnings.cannotRenderAnyCommerceComponent('PlanDetails'), {
           code: CANNOT_RENDER_BILLING_DISABLED_ERROR_CODE,
         });
       }
       return;
     }
     void this.#componentControls
-      .ensureMounted({ preloadHint: 'SubscriptionDetails' })
-      .then(controls => controls.openDrawer('subscriptionDetails', props || {}));
+      .ensureMounted({ preloadHint: 'PlanDetails' })
+      .then(controls => controls.openDrawer('planDetails', props || {}));
   };
 
-  public __internal_closeSubscriptionDetails = (): void => {
+  public __internal_closePlanDetails = (): void => {
     this.assertComponentsReady(this.#componentControls);
-    void this.#componentControls.ensureMounted().then(controls => controls.closeDrawer('subscriptionDetails'));
+    void this.#componentControls.ensureMounted().then(controls => controls.closeDrawer('planDetails'));
   };
 
   public __internal_openReverification = (props?: __internal_UserVerificationModalProps): void => {

diff --git a/packages/clerk-js/src/core/warnings.ts b/packages/clerk-js/src/core/warnings.ts
@@ -11,7 +11,7 @@ const createMessageForDisabledOrganizations = (
     `The <${componentName}/> cannot be rendered when the feature is turned off. Visit 'dashboard.clerk.com' to enable the feature. Since the feature is turned off, this is no-op.`,
   );
 };
-const createMessageForDisabledCommerce = (componentName: 'PricingTable' | 'Checkout' | 'SubscriptionDetails') => {
+const createMessageForDisabledCommerce = (componentName: 'PricingTable' | 'Checkout' | 'PlanDetails') => {
   return formatWarning(
     `The <${componentName}/> component cannot be rendered when billing is disabled. Visit 'https://dashboard.clerk.com/last-active?path=billing/settings' to follow the necessary steps to enable commerce. Since commerce is disabled, this is no-op.`,
   );

diff --git a/packages/clerk-js/src/ui/Components.tsx b/packages/clerk-js/src/ui/Components.tsx
@@ -1,7 +1,7 @@
 import { createDeferredPromise } from '@clerk/shared/utils';
 import type {
   __experimental_CheckoutProps,
-  __experimental_SubscriptionDetailsProps,
+  __experimental_PlanDetailsProps,
   __internal_UserVerificationProps,
   Appearance,
   Clerk,
@@ -37,7 +37,7 @@ import {
   UserVerificationModal,
   WaitlistModal,
 } from './lazyModules/components';
-import { MountedCheckoutDrawer, MountedSubscriptionDetailDrawer } from './lazyModules/drawers';
+import { MountedCheckoutDrawer, MountedPlanDetailDrawer } from './lazyModules/drawers';
 import {
   LazyComponentRenderer,
   LazyImpersonationFabProvider,
@@ -107,16 +107,16 @@ export type ComponentControls = {
       notify?: boolean;
     },
   ) => void;
-  openDrawer: <T extends 'checkout' | 'subscriptionDetails'>(
+  openDrawer: <T extends 'checkout' | 'planDetails'>(
     drawer: T,
     props: T extends 'checkout'
       ? __experimental_CheckoutProps
-      : T extends 'subscriptionDetails'
-        ? __experimental_SubscriptionDetailsProps
+      : T extends 'planDetails'
+        ? __experimental_PlanDetailsProps
         : never,
   ) => void;
   closeDrawer: (
-    drawer: 'checkout' | 'subscriptionDetails',
+    drawer: 'checkout' | 'planDetails',
     options?: {
       notify?: boolean;
     },
@@ -157,9 +157,9 @@ interface ComponentsState {
     open: false;
     props: null | __experimental_CheckoutProps;
   };
-  subscriptionDetailsDrawer: {
+  planDetailsDrawer: {
     open: false;
-    props: null | __experimental_SubscriptionDetailsProps;
+    props: null | __experimental_PlanDetailsProps;
   };
   nodes: Map<HTMLDivElement, HtmlNodeOptions>;
   impersonationFab: boolean;
@@ -246,7 +246,7 @@ const Components = (props: ComponentsProps) => {
       open: false,
       props: null,
     },
-    subscriptionDetailsDrawer: {
+    planDetailsDrawer: {
       open: false,
       props: null,
     },
@@ -265,7 +265,7 @@ const Components = (props: ComponentsProps) => {
     waitlistModal,
     blankCaptchaModal,
     checkoutDrawer,
-    subscriptionDetailsDrawer,
+    planDetailsDrawer,
     nodes,
   } = state;
 
@@ -578,10 +578,10 @@ const Components = (props: ComponentsProps) => {
           onOpenChange={() => componentsControls.closeDrawer('checkout')}
         />
 
-        <MountedSubscriptionDetailDrawer
+        <MountedPlanDetailDrawer
           appearance={state.appearance}
-          subscriptionDetailsDrawer={subscriptionDetailsDrawer}
-          onOpenChange={() => componentsControls.closeDrawer('subscriptionDetails')}
+          planDetailsDrawer={planDetailsDrawer}
+          onOpenChange={() => componentsControls.closeDrawer('planDetails')}
         />
 
         {state.impersonationFab && (

diff --git a/...nts/Subscriptions/SubscriptionDetails.tsx → ...s/src/ui/components/Plans/PlanDetails.tsx b/...nts/Subscriptions/SubscriptionDetails.tsx → ...s/src/ui/components/Plans/PlanDetails.tsx
@@ -3,7 +3,7 @@ import type {
   __experimental_CommercePlanResource,
   __experimental_CommerceSubscriptionPlanPeriod,
   __experimental_CommerceSubscriptionResource,
-  __experimental_SubscriptionDetailsProps,
+  __experimental_PlanDetailsProps,
   ClerkAPIError,
   ClerkRuntimeError,
 } from '@clerk/types';
@@ -27,22 +27,22 @@ import { Alert, Avatar, Drawer, SegmentedControl, useDrawerContext } from '../..
 import { InformationCircle } from '../../icons';
 import { formatDate, handleError } from '../../utils';
 
-export const SubscriptionDetails = (props: __experimental_SubscriptionDetailsProps) => {
+export const PlanDetails = (props: __experimental_PlanDetailsProps) => {
   return (
     <SubscriberTypeContext.Provider value={props.subscriberType || 'user'}>
       <PlansContextProvider>
-        <_SubscriptionDetails {...props} />
+        <_PlanDetails {...props} />
       </PlansContextProvider>
     </SubscriberTypeContext.Provider>
   );
 };
 
-const _SubscriptionDetails = ({
+const _PlanDetails = ({
   plan,
   onSubscriptionCancel,
   portalId,
   planPeriod: _planPeriod = 'month',
-}: __experimental_SubscriptionDetailsProps) => {
+}: __experimental_PlanDetailsProps) => {
   const clerk = useClerk();
   const { organization } = useOrganization();
   const [showConfirmation, setShowConfirmation] = useState(false);
@@ -134,7 +134,7 @@ const _SubscriptionDetails = ({
       {hasFeatures ? (
         <Drawer.Body>
           <Text
-            elementDescriptor={descriptors.subscriptionDetailCaption}
+            elementDescriptor={descriptors.planDetailCaption}
             variant={'caption'}
             localizationKey={localizationKeys('__experimental_commerce.availableFeatures')}
             colorScheme='secondary'
@@ -144,7 +144,7 @@ const _SubscriptionDetails = ({
             })}
           />
           <Box
-            elementDescriptor={descriptors.subscriptionDetailFeaturesList}
+            elementDescriptor={descriptors.planDetailFeaturesList}
             as='ul'
             role='list'
             sx={t => ({
@@ -156,7 +156,7 @@ const _SubscriptionDetails = ({
             {features.map(feature => (
               <Box
                 key={feature.id}
-                elementDescriptor={descriptors.subscriptionDetailFeaturesListItem}
+                elementDescriptor={descriptors.planDetailFeaturesListItem}
                 as='li'
                 sx={t => ({
                   display: 'flex',
@@ -173,9 +173,9 @@ const _SubscriptionDetails = ({
                     imageUrl={feature.avatarUrl}
                   />
                 ) : null}
-                <Span elementDescriptor={descriptors.subscriptionDetailFeaturesListItemContent}>
+                <Span elementDescriptor={descriptors.planDetailFeaturesListItemContent}>
                   <Text
-                    elementDescriptor={descriptors.subscriptionDetailFeaturesListItemTitle}
+                    elementDescriptor={descriptors.planDetailFeaturesListItemTitle}
                     colorScheme='body'
                     sx={t => ({
                       fontWeight: t.fontWeights.$medium,
@@ -185,7 +185,7 @@ const _SubscriptionDetails = ({
                   </Text>
                   {feature.description ? (
                     <Text
-                      elementDescriptor={descriptors.subscriptionDetailFeaturesListItemDescription}
+                      elementDescriptor={descriptors.planDetailFeaturesListItemDescription}
                       colorScheme='secondary'
                       sx={t => ({
                         marginBlockStart: t.space.$0x25,
@@ -319,7 +319,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
   return (
     <Box
       ref={ref}
-      elementDescriptor={descriptors.subscriptionDetailHeader}
+      elementDescriptor={descriptors.planDetailHeader}
       sx={t => ({
         width: '100%',
         padding: t.space.$4,
@@ -340,7 +340,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
 
       {plan.avatarUrl ? (
         <Avatar
-          boxElementDescriptor={descriptors.subscriptionDetailAvatar}
+          boxElementDescriptor={descriptors.planDetailAvatar}
           size={_ => 40}
           title={plan.name}
           initials={plan.name[0]}
@@ -353,20 +353,20 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
       ) : null}
       {subscription ? (
         <Box
-          elementDescriptor={descriptors.subscriptionDetailBadgeContainer}
+          elementDescriptor={descriptors.planDetailBadgeContainer}
           sx={t => ({
             marginBlockEnd: t.space.$3,
           })}
         >
           {subscription.status === 'active' ? (
             <Badge
-              elementDescriptor={descriptors.subscriptionDetailBadge}
+              elementDescriptor={descriptors.planDetailBadge}
               localizationKey={localizationKeys('badge__currentPlan')}
               colorScheme={'secondary'}
             />
           ) : (
             <Badge
-              elementDescriptor={descriptors.subscriptionDetailBadge}
+              elementDescriptor={descriptors.planDetailBadge}
               localizationKey={localizationKeys('badge__upcomingPlan')}
               colorScheme={'primary'}
             />
@@ -380,15 +380,15 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
         })}
       >
         <Heading
-          elementDescriptor={descriptors.subscriptionDetailTitle}
+          elementDescriptor={descriptors.planDetailTitle}
           as='h2'
           textVariant='h2'
         >
           {plan.name}
         </Heading>
         {plan.description ? (
           <Text
-            elementDescriptor={descriptors.subscriptionDetailDescription}
+            elementDescriptor={descriptors.planDetailDescription}
             variant='subtitle'
             colorScheme='secondary'
           >
@@ -399,7 +399,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
 
       {plan.amount > 0 ? (
         <Flex
-          elementDescriptor={descriptors.subscriptionDetailFeeContainer}
+          elementDescriptor={descriptors.planDetailFeeContainer}
           align='center'
           wrap='wrap'
           sx={t => ({
@@ -409,7 +409,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
         >
           <>
             <Text
-              elementDescriptor={descriptors.subscriptionDetailFee}
+              elementDescriptor={descriptors.planDetailFee}
               variant='h1'
               colorScheme='body'
             >
@@ -419,7 +419,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
                 : plan.amountFormatted}
             </Text>
             <Text
-              elementDescriptor={descriptors.subscriptionDetailFeePeriod}
+              elementDescriptor={descriptors.planDetailFeePeriod}
               variant='caption'
               colorScheme='secondary'
               sx={t => ({
@@ -433,7 +433,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
             />
             {plan.annualMonthlyAmount > 0 ? (
               <Box
-                elementDescriptor={descriptors.subscriptionDetailFeePeriodNotice}
+                elementDescriptor={descriptors.planDetailFeePeriodNotice}
                 sx={[
                   _ => ({
                     width: '100%',
@@ -448,14 +448,14 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
                 }
               >
                 <Box
-                  elementDescriptor={descriptors.subscriptionDetailFeePeriodNoticeInner}
+                  elementDescriptor={descriptors.planDetailFeePeriodNoticeInner}
                   sx={{
                     overflow: 'hidden',
                     minHeight: 0,
                   }}
                 >
                   <Text
-                    elementDescriptor={descriptors.subscriptionDetailFeePeriodNoticeLabel}
+                    elementDescriptor={descriptors.planDetailFeePeriodNoticeLabel}
                     variant='caption'
                     colorScheme='secondary'
                     sx={t => ({
@@ -482,7 +482,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
 
       {!!subscription && (
         <Text
-          elementDescriptor={descriptors.subscriptionDetailCaption}
+          elementDescriptor={descriptors.planDetailCaption}
           variant={'caption'}
           localizationKey={captionForSubscription(subscription)}
           colorScheme='secondary'
@@ -494,7 +494,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
 
       {!subscription && plan.annualMonthlyAmount > 0 ? (
         <Box
-          elementDescriptor={descriptors.subscriptionDetailPeriodToggle}
+          elementDescriptor={descriptors.planDetailPeriodToggle}
           sx={t => ({
             display: 'flex',
             marginTop: t.space.$3,

diff --git a/packages/clerk-js/src/ui/components/Plans/index.tsx b/packages/clerk-js/src/ui/components/Plans/index.tsx
@@ -0,0 +1 @@
+export * from './PlanDetails';
diff --git a/packages/clerk-js/src/ui/components/PricingTable/FreePlanRow.tsx b/packages/clerk-js/src/ui/components/PricingTable/FreePlanRow.tsx
@@ -18,7 +18,7 @@ export const FreePlanRow = () => {
       return;
     }
 
-    clerk.__internal_openSubscriptionDetails({
+    clerk.__internal_openPlanDetails({
       plan: defaultFreePlan,
       subscriberType: subscriberType,
       portalId:

diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
@@ -116,7 +116,7 @@ function Card(props: CardProps) {
   const { buttonPropsForPlan } = usePlansContext();
 
   const showPlanDetails = () => {
-    clerk.__internal_openSubscriptionDetails({
+    clerk.__internal_openPlanDetails({
       plan,
       subscriberType,
       planPeriod,

diff --git a/packages/clerk-js/src/ui/components/Subscriptions/index.tsx b/packages/clerk-js/src/ui/components/Subscriptions/index.tsx
@@ -1,2 +1 @@
-export * from './SubscriptionDetails';
 export * from './SubscriptionsList';
diff --git a/packages/clerk-js/src/ui/contexts/components/Plans.tsx b/packages/clerk-js/src/ui/contexts/components/Plans.tsx
@@ -174,7 +174,7 @@ export const usePlansContext = () => {
       const subscription = activeOrUpcomingSubscription(plan);
 
       if (subscription && !subscription.canceledAt) {
-        clerk.__internal_openSubscriptionDetails({
+        clerk.__internal_openPlanDetails({
           plan,
           subscriberType,
           onSubscriptionCancel: () => {
Original file line number	Diff line number	Diff line change
		@@ -1,2 +1 @@
		export * from './SubscriptionDetails';
		export * from './SubscriptionsList';