From e10824c0f691f100be52aef18fd77e224c7e57c0 Mon Sep 17 00:00:00 2001
From: Keiran Flanigan <keiran@aeliox.com>
Date: Sat, 3 May 2025 10:38:58 -0500
Subject: [PATCH 1/2] feat(clerk-js,localizations): Add support for switching
 to annual plan period of existing monthly subscription

---
 .../src/ui/components/Plans/PlanDetails.tsx   | 69 ++++++++++++-------
 packages/localizations/src/en-US.ts           |  1 +
 packages/types/src/localization.ts            |  1 +
 3 files changed, 45 insertions(+), 26 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx b/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
index d5c95322f00..cb4a0f9d21f 100644
--- a/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
+++ b/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
@@ -15,6 +15,7 @@ import {
   Badge,
   Box,
   Button,
+  Col,
   descriptors,
   Flex,
   Heading,
@@ -89,12 +90,16 @@ const _PlanDetails = ({
       });
   };
 
-  const openCheckout = () => {
+  type OpenCheckoutProps = {
+    planPeriod?: __experimental_CommerceSubscriptionPlanPeriod;
+  };
+
+  const openCheckout = (props?: OpenCheckoutProps) => {
     handleClose();
 
     // if the plan doesn't support annual, use monthly
-    let _planPeriod = planPeriod;
-    if (planPeriod === 'annual' && plan.annualMonthlyAmount === 0) {
+    let _planPeriod = props?.planPeriod || planPeriod;
+    if (_planPeriod === 'annual' && plan.annualMonthlyAmount === 0) {
       _planPeriod = 'month';
     }
 
@@ -210,24 +215,36 @@ const _PlanDetails = ({
                 block
                 textVariant='buttonLarge'
                 {...buttonPropsForPlan({ plan })}
-                onClick={openCheckout}
+                onClick={() => openCheckout()}
               />
             ) : (
-              <Button
-                block
-                variant='bordered'
-                colorScheme='secondary'
-                textVariant='buttonLarge'
-                onClick={() => setShowConfirmation(true)}
-                localizationKey={localizationKeys('__experimental_commerce.cancelSubscription')}
-              />
+              <Col gap={4}>
+                {!!subscription && subscription.planPeriod === 'month' && plan.annualMonthlyAmount > 0 ? (
+                  <Button
+                    block
+                    variant='bordered'
+                    colorScheme='secondary'
+                    textVariant='buttonLarge'
+                    onClick={() => openCheckout({ planPeriod: 'annual' })}
+                    localizationKey={localizationKeys('__experimental_commerce.switchToAnnual')}
+                  />
+                ) : null}
+                <Button
+                  block
+                  variant='bordered'
+                  colorScheme='danger'
+                  textVariant='buttonLarge'
+                  onClick={() => setShowConfirmation(true)}
+                  localizationKey={localizationKeys('__experimental_commerce.cancelSubscription')}
+                />
+              </Col>
             )
           ) : (
             <Button
               block
               textVariant='buttonLarge'
               {...buttonPropsForPlan({ plan })}
-              onClick={openCheckout}
+              onClick={() => openCheckout()}
             />
           )}
         </Drawer.Footer>
@@ -481,19 +498,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
         </Flex>
       ) : null}
 
-      {!!subscription && (
-        <Text
-          elementDescriptor={descriptors.planDetailCaption}
-          variant={'caption'}
-          localizationKey={captionForSubscription(subscription)}
-          colorScheme='secondary'
-          sx={t => ({
-            marginTop: t.space.$3,
-          })}
-        />
-      )}
-
-      {!subscription && plan.annualMonthlyAmount > 0 ? (
+      {!subscription || (subscription.planPeriod === 'month' && plan.annualMonthlyAmount > 0) ? (
         <Box
           elementDescriptor={descriptors.planDetailPeriodToggle}
           sx={t => ({
@@ -519,6 +524,18 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>((props, ref) => {
           </SegmentedControl.Root>
         </Box>
       ) : null}
+
+      {!!subscription && (
+        <Text
+          elementDescriptor={descriptors.planDetailCaption}
+          variant={'caption'}
+          localizationKey={captionForSubscription(subscription)}
+          colorScheme='secondary'
+          sx={t => ({
+            marginTop: t.space.$3,
+          })}
+        />
+      )}
     </Box>
   );
 });
diff --git a/packages/localizations/src/en-US.ts b/packages/localizations/src/en-US.ts
index 9f88babbfd2..a33b67a7b56 100644
--- a/packages/localizations/src/en-US.ts
+++ b/packages/localizations/src/en-US.ts
@@ -29,6 +29,7 @@ export const enUS: LocalizationResource = {
     month: 'Month',
     reSubscribe: 'Re-subscribe',
     switchPlan: 'Switch to this plan',
+    switchToAnnual: 'Switch to annual',
     defaultFreePlanActive: "You're currently on the Free plan",
     availableFeatures: 'Available features',
     viewFeatures: 'View features',
diff --git a/packages/types/src/localization.ts b/packages/types/src/localization.ts
index 86fb84dd016..98426328120 100644
--- a/packages/types/src/localization.ts
+++ b/packages/types/src/localization.ts
@@ -114,6 +114,7 @@ type _LocalizationResource = {
     keepSubscription: LocalizationValue;
     reSubscribe: LocalizationValue;
     switchPlan: LocalizationValue;
+    switchToAnnual: LocalizationValue;
     billedAnnually: LocalizationValue;
     accountFunds: LocalizationValue;
     defaultFreePlanActive: LocalizationValue;

From 3df861969ac4c5e7e6975611b10ddfa86195256e Mon Sep 17 00:00:00 2001
From: Keiran Flanigan <keiran@aeliox.com>
Date: Sat, 3 May 2025 10:47:46 -0500
Subject: [PATCH 2/2] changeset

---
 .changeset/sad-teeth-argue.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/sad-teeth-argue.md

diff --git a/.changeset/sad-teeth-argue.md b/.changeset/sad-teeth-argue.md
new file mode 100644
index 00000000000..2239be50aa7
--- /dev/null
+++ b/.changeset/sad-teeth-argue.md
@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': patch
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Allow switching from an existing monthly subscription to an annual subscription for the same plan