From f464c34acf805359b415ee4ee3112c15f5cde76e Mon Sep 17 00:00:00 2001
From: Nikos Douvlis <nikosdouvlis@gmail.com>
Date: Fri, 9 May 2025 15:42:42 +0300
Subject: [PATCH 1/2] fix(clerk-js): Add planPeriodStart to CommerceCheckout

---
 .../clerk-js/src/core/resources/CommerceCheckout.ts  | 12 +++---------
 .../src/ui/components/Checkout/CheckoutComplete.tsx  |  4 ++--
 packages/types/src/commerce.ts                       |  2 +-
 packages/types/src/json.ts                           |  2 +-
 4 files changed, 7 insertions(+), 13 deletions(-)

diff --git a/packages/clerk-js/src/core/resources/CommerceCheckout.ts b/packages/clerk-js/src/core/resources/CommerceCheckout.ts
index 9d46ab81753..d4114ecb24b 100644
--- a/packages/clerk-js/src/core/resources/CommerceCheckout.ts
+++ b/packages/clerk-js/src/core/resources/CommerceCheckout.ts
@@ -8,13 +8,7 @@ import type {
 } from '@clerk/types';
 
 import { commerceTotalsFromJSON } from '../../utils';
-import {
-  BaseResource,
-  CommercePaymentSource,
-  CommercePlan,
-  CommerceSubscription,
-  isClerkAPIResponseError,
-} from './internal';
+import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
 export class CommerceCheckout extends BaseResource implements CommerceCheckoutResource {
   id!: string;
@@ -24,8 +18,8 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
   paymentSource?: CommercePaymentSource;
   plan!: CommercePlan;
   planPeriod!: CommerceSubscriptionPlanPeriod;
+  planPeriodStart!: number | undefined;
   status!: string;
-  subscription?: CommerceSubscription;
   totals!: CommerceCheckoutTotals;
   isImmediatePlanChange!: boolean;
 
@@ -47,8 +41,8 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
     this.paymentSource = data.payment_source ? new CommercePaymentSource(data.payment_source) : undefined;
     this.plan = new CommercePlan(data.plan);
     this.planPeriod = data.plan_period;
+    this.planPeriodStart = data.plan_period_start;
     this.status = data.status;
-    this.subscription = data.subscription ? new CommerceSubscription(data.subscription) : undefined;
     this.totals = commerceTotalsFromJSON(data.totals);
     this.isImmediatePlanChange = data.is_immediate_plan_change;
     return this;
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
index bd536dbdd7b..a3ac5ab4f90 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
@@ -261,8 +261,8 @@ export const CheckoutComplete = ({
                       ? `${capitalize(checkout.paymentSource.paymentMethod)}`
                       : `${capitalize(checkout.paymentSource.cardType)} ⋯ ${checkout.paymentSource.last4}`
                     : '–'
-                  : checkout.subscription?.periodStart
-                    ? formatDate(new Date(checkout.subscription.periodStart))
+                  : checkout.planPeriodStart
+                    ? formatDate(new Date(checkout.planPeriodStart))
                     : '–'
               }
             />
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 380a9ef0c57..d38ef8be089 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -199,9 +199,9 @@ export interface CommerceCheckoutResource extends ClerkResource {
   paymentSource?: CommercePaymentSourceResource;
   plan: CommercePlanResource;
   planPeriod: CommerceSubscriptionPlanPeriod;
+  planPeriodStart?: number;
   status: string;
   totals: CommerceCheckoutTotals;
-  subscription?: CommerceSubscriptionResource;
   confirm: (params: ConfirmCheckoutParams) => Promise<CommerceCheckoutResource>;
   isImmediatePlanChange: boolean;
 }
diff --git a/packages/types/src/json.ts b/packages/types/src/json.ts
index 1d1c9910ec5..79b1c5ad6ae 100644
--- a/packages/types/src/json.ts
+++ b/packages/types/src/json.ts
@@ -712,8 +712,8 @@ export interface CommerceCheckoutJSON extends ClerkResourceJSON {
   payment_source?: CommercePaymentSourceJSON;
   plan: CommercePlanJSON;
   plan_period: CommerceSubscriptionPlanPeriod;
+  plan_period_start?: number;
   status: string;
-  subscription?: CommerceSubscriptionJSON;
   totals: CommerceCheckoutTotalsJSON;
   is_immediate_plan_change: boolean;
 }

From 23c19fb9cf7ed3469bcc2d9116382d907441862c Mon Sep 17 00:00:00 2001
From: Nikos Douvlis <nikosdouvlis@gmail.com>
Date: Fri, 9 May 2025 15:47:15 +0300
Subject: [PATCH 2/2] Create twenty-monkeys-camp.md

---
 .changeset/twenty-monkeys-camp.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/twenty-monkeys-camp.md

diff --git a/.changeset/twenty-monkeys-camp.md b/.changeset/twenty-monkeys-camp.md
new file mode 100644
index 00000000000..7e0b4d2823a
--- /dev/null
+++ b/.changeset/twenty-monkeys-camp.md
@@ -0,0 +1,7 @@
+---
+"@clerk/clerk-js": patch
+"@clerk/types": patch
+---
+
+Fix the "Plan starts at" date when a user downgrades from a paid plan to the free plan
+