From eb79d11f757097e7b0dd2c47ab9f1ef421b7163c Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Tue, 1 Jul 2025 17:47:38 +0300
Subject: [PATCH] chore(clerk-js,types): Convert date properties from number to
 Date in CommerceSubscriptionResource

---
 .changeset/funny-ducks-boil.md                | 15 +++++++++
 .../core/resources/CommerceSubscription.ts    | 13 ++++++++
 .../src/ui/components/Plans/PlanDetails.tsx   |  5 +--
 .../components/PricingTable/PricingTable.tsx  |  2 +-
 .../PricingTable/PricingTableDefault.tsx      |  4 +--
 .../Subscriptions/SubscriptionsList.tsx       |  2 +-
 .../src/ui/contexts/components/Plans.tsx      | 31 +++++++++++--------
 packages/types/src/commerce.ts                | 13 ++++++++
 packages/types/src/json.ts                    |  1 +
 9 files changed, 67 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/funny-ducks-boil.md

diff --git a/.changeset/funny-ducks-boil.md b/.changeset/funny-ducks-boil.md
new file mode 100644
index 00000000000..d037c7a1a7c
--- /dev/null
+++ b/.changeset/funny-ducks-boil.md
@@ -0,0 +1,15 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Convert date properties from number to Date in CommerceSubscriptionResource
+Deprecates fields of type `number`
+- subscription.periodStart
+- subscription.periodEnd
+- subscription.canceledAt
+Introduces fields of type `Date`
+- subscription.periodStartDate
+- subscription.periodEndDate
+- subscription.canceledAtDate
+- subscription.createdAt
diff --git a/packages/clerk-js/src/core/resources/CommerceSubscription.ts b/packages/clerk-js/src/core/resources/CommerceSubscription.ts
index fe63c472629..ac4d949fdf4 100644
--- a/packages/clerk-js/src/core/resources/CommerceSubscription.ts
+++ b/packages/clerk-js/src/core/resources/CommerceSubscription.ts
@@ -8,6 +8,8 @@ import type {
   DeletedObjectJSON,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceMoneyFromJSON } from '../../utils';
 import { BaseResource, CommercePlan, DeletedObject } from './internal';
 
@@ -17,6 +19,10 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
   plan!: CommercePlan;
   planPeriod!: CommerceSubscriptionPlanPeriod;
   status!: CommerceSubscriptionStatus;
+  createdAt!: Date;
+  periodStartDate!: Date;
+  periodEndDate!: Date | null;
+  canceledAtDate!: Date | null;
   periodStart!: number;
   periodEnd!: number;
   canceledAt!: number | null;
@@ -24,6 +30,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
   credit?: {
     amount: CommerceMoney;
   };
+
   constructor(data: CommerceSubscriptionJSON) {
     super();
     this.fromJSON(data);
@@ -42,6 +49,12 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
     this.periodStart = data.period_start;
     this.periodEnd = data.period_end;
     this.canceledAt = data.canceled_at;
+
+    this.createdAt = unixEpochToDate(data.created_at);
+    this.periodStartDate = unixEpochToDate(data.period_start);
+    this.periodEndDate = data.period_end ? unixEpochToDate(data.period_end) : null;
+    this.canceledAtDate = data.canceled_at ? unixEpochToDate(data.canceled_at) : null;
+
     this.amount = data.amount ? commerceMoneyFromJSON(data.amount) : undefined;
     this.credit = data.credit && data.credit.amount ? { amount: commerceMoneyFromJSON(data.credit.amount) } : undefined;
     return this;
diff --git a/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx b/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
index 3a967e241ea..a64274a1c15 100644
--- a/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
+++ b/packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx
@@ -210,7 +210,7 @@ const PlanDetailsInternal = ({
       {(!plan.isDefault && !isDefaultPlanImplicitlyActiveOrUpcoming) || !subscription ? (
         <Drawer.Footer>
           {subscription ? (
-            subscription.canceledAt ? (
+            subscription.canceledAtDate ? (
               <Button
                 block
                 textVariant='buttonLarge'
@@ -318,7 +318,8 @@ const PlanDetailsInternal = ({
                 ? localizationKeys('commerce.cancelSubscriptionNoCharge')
                 : localizationKeys('commerce.cancelSubscriptionAccessUntil', {
                     plan: subscription.plan.name,
-                    date: subscription.periodEnd,
+                    // @ts-expect-error this will always be defined in this case.
+                    date: subscription.periodEndDate,
                   })
             }
           />
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx
index 710d9191463..6151c14e488 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx
@@ -24,7 +24,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 
       // don't pay attention to the default plan
       const activeSubscription = subscriptions?.find(
-        sub => !sub.canceledAt && sub.status === 'active' && !sub.plan.isDefault,
+        sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
       );
       if (activeSubscription) {
         return activeSubscription.planPeriod;
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
index fdf5d8d893a..27db2422f13 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
@@ -143,7 +143,7 @@ function Card(props: CardProps) {
     shouldShowFooter = true;
     shouldShowFooterNotice = true;
   } else if (subscription.status === 'active') {
-    if (subscription.canceledAt) {
+    if (subscription.canceledAtDate) {
       shouldShowFooter = true;
       shouldShowFooterNotice = false;
     } else if (planPeriod !== subscription.planPeriod && plan.annualMonthlyAmount > 0) {
@@ -253,7 +253,7 @@ function Card(props: CardProps) {
                 elementDescriptor={descriptors.pricingTableCardFooterNotice}
                 variant={isCompact ? 'buttonSmall' : 'buttonLarge'}
                 localizationKey={localizationKeys('badge__startsAt', {
-                  date: subscription?.periodStart,
+                  date: subscription?.periodStartDate,
                 })}
                 colorScheme='secondary'
                 sx={t => ({
diff --git a/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx b/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx
index 4c2645deab3..9c08b9f1258 100644
--- a/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx
+++ b/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx
@@ -125,7 +125,7 @@ export function SubscriptionsList({
                       >
                         {subscription.plan.name}
                       </Text>
-                      {sortedSubscriptions.length > 1 || !!subscription.canceledAt ? (
+                      {sortedSubscriptions.length > 1 || !!subscription.canceledAtDate ? (
                         <Badge
                           colorScheme={subscription.status === 'active' ? 'secondary' : 'primary'}
                           localizationKey={
diff --git a/packages/clerk-js/src/ui/contexts/components/Plans.tsx b/packages/clerk-js/src/ui/contexts/components/Plans.tsx
index c200efee2fb..debc44894c5 100644
--- a/packages/clerk-js/src/ui/contexts/components/Plans.tsx
+++ b/packages/clerk-js/src/ui/contexts/components/Plans.tsx
@@ -98,9 +98,9 @@ export const useSubscriptions = () => {
     if (
       isSignedIn &&
       defaultFreePlan &&
-      (_subscriptions.data.length === 0 || !_subscriptions.data.some(subscription => !subscription.canceledAt))
+      (_subscriptions.data.length === 0 || !_subscriptions.data.some(subscription => !subscription.canceledAtDate))
     ) {
-      const canceledSubscription = _subscriptions.data.find(subscription => subscription.canceledAt);
+      const canceledSubscription = _subscriptions.data.find(subscription => subscription.canceledAtDate);
       return [
         ..._subscriptions.data,
         new CommerceSubscription({
@@ -111,7 +111,8 @@ export const useSubscriptions = () => {
           plan_period: 'month',
           canceled_at: null,
           status: _subscriptions.data.length === 0 ? 'active' : 'upcoming',
-          period_start: canceledSubscription?.periodEnd || 0,
+          created_at: canceledSubscription?.periodEndDate?.getTime() || 0,
+          period_start: canceledSubscription?.periodEndDate?.getTime() || 0,
           period_end: 0,
         }),
       ];
@@ -190,7 +191,7 @@ export const usePlansContext = () => {
   // should the default plan be shown as active
   const isDefaultPlanImplicitlyActiveOrUpcoming = useMemo(() => {
     // are there no subscriptions or are all subscriptions canceled
-    return subscriptions.length === 0 || !subscriptions.some(subscription => !subscription.canceledAt);
+    return subscriptions.length === 0 || !subscriptions.some(subscription => !subscription.canceledAtDate);
   }, [subscriptions]);
 
   // return the active or upcoming subscription for a plan if it exists
@@ -239,7 +240,7 @@ export const usePlansContext = () => {
     ({ plan, subscription: sub }: { plan?: CommercePlanResource; subscription?: CommerceSubscriptionResource }) => {
       const subscription = sub ?? (plan ? activeOrUpcomingSubscription(plan) : undefined);
 
-      return !subscription || !subscription.canceledAt;
+      return !subscription || !subscription.canceledAtDate;
     },
     [activeOrUpcomingSubscription],
   );
@@ -282,7 +283,7 @@ export const usePlansContext = () => {
       const getLocalizationKey = () => {
         // Handle subscription cases
         if (subscription) {
-          if (_selectedPlanPeriod !== subscription.planPeriod && subscription.canceledAt) {
+          if (_selectedPlanPeriod !== subscription.planPeriod && subscription.canceledAtDate) {
             if (_selectedPlanPeriod === 'month') {
               return localizationKeys('commerce.switchToMonthly');
             }
@@ -292,7 +293,7 @@ export const usePlansContext = () => {
             }
           }
 
-          if (subscription.canceledAt) {
+          if (subscription.canceledAtDate) {
             return localizationKeys('commerce.reSubscribe');
           }
 
@@ -332,12 +333,16 @@ export const usePlansContext = () => {
 
   const captionForSubscription = useCallback((subscription: CommerceSubscriptionResource) => {
     if (subscription.status === 'upcoming') {
-      return localizationKeys('badge__startsAt', { date: subscription.periodStart });
-    } else if (subscription.canceledAt) {
-      return localizationKeys('badge__canceledEndsAt', { date: subscription.periodEnd });
-    } else {
-      return localizationKeys('badge__renewsAt', { date: subscription.periodEnd });
+      return localizationKeys('badge__startsAt', { date: subscription.periodStartDate });
     }
+    if (subscription.canceledAtDate) {
+      // @ts-expect-error `periodEndDate` is always defined when `canceledAtDate` exists
+      return localizationKeys('badge__canceledEndsAt', { date: subscription.periodEndDate });
+    }
+    if (subscription.periodEndDate) {
+      return localizationKeys('badge__renewsAt', { date: subscription.periodEndDate });
+    }
+    return;
   }, []);
 
   // handle the selection of a plan, either by opening the subscription details or checkout
@@ -355,7 +360,7 @@ export const usePlansContext = () => {
 
       const portalRoot = getClosestProfileScrollBox(mode, event);
 
-      if (subscription && subscription.planPeriod === planPeriod && !subscription.canceledAt) {
+      if (subscription && subscription.planPeriod === planPeriod && !subscription.canceledAtDate) {
         clerk.__internal_openPlanDetails({
           plan,
           initialPlanPeriod: planPeriod,
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 3caf459548d..ea041db90d9 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -155,8 +155,21 @@ export interface CommerceSubscriptionResource extends ClerkResource {
   plan: CommercePlanResource;
   planPeriod: CommerceSubscriptionPlanPeriod;
   status: CommerceSubscriptionStatus;
+  createdAt: Date;
+  periodStartDate: Date;
+  periodEndDate: Date | null;
+  canceledAtDate: Date | null;
+  /**
+   * @deprecated Use `periodStartDate` instead
+   */
   periodStart: number;
+  /**
+   * @deprecated Use `periodEndDate` instead
+   */
   periodEnd: number;
+  /**
+   * @deprecated Use `canceledAtDate` instead
+   */
   canceledAt: number | null;
   amount?: CommerceMoney;
   credit?: {
diff --git a/packages/types/src/json.ts b/packages/types/src/json.ts
index dbf38dcb0c7..779d0807f0c 100644
--- a/packages/types/src/json.ts
+++ b/packages/types/src/json.ts
@@ -701,6 +701,7 @@ export interface CommerceSubscriptionJSON extends ClerkResourceJSON {
   plan: CommercePlanJSON;
   plan_period: CommerceSubscriptionPlanPeriod;
   status: CommerceSubscriptionStatus;
+  created_at: number;
   period_start: number;
   period_end: number;
   canceled_at: number | null;