chore(clerk-js,types): Update checkout flow to support free trials

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+ - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
  "files": [
- { "path": "./dist/clerk.js", "maxSize": "622KB" },
+ { "path": "./dist/clerk.js", "maxSize": "622.25KB" },
  { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
  { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
  { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
  { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
- { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+ { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
  { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
  { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
  })),
  });
 
- //@ts-expect-error
+ //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
  global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
  return null;
  }
  };
+
+ // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+ HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+ if (contextType === '2d') {
+ return {
+ fillRect: jest.fn(),
+ getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+ } as unknown as CanvasRenderingContext2D;
+ }
+ if (contextType === 'webgl' || contextType === 'webgl2') {
+ return {} as unknown as WebGLRenderingContext;
+ }
+ return null;
+ }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
  ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  status!: 'needs_confirmation' | 'completed';
  totals!: CommerceCheckoutTotals;
  isImmediatePlanChange!: boolean;
+ freeTrialEndsAt!: Date | null;
 
  constructor(data: CommerceCheckoutJSON, orgId?: string) {
  super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
  this.status = data.status;
  this.totals = commerceTotalsFromJSON(data.totals);
  this.isImmediatePlanChange = data.is_immediate_plan_change;
+ this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
  return this;
  }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
  }
  : null;
  this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
- this.eligibleForFreeTrial = data.eligible_for_free_trial;
+ this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
  return this;
  }
 }

packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
  const { setIsOpen } = useDrawerContext();
  const { newSubscriptionRedirectUrl } = useCheckoutContext();
  const { checkout } = useCheckout();
- const { totals, paymentSource, planPeriodStart } = checkout;
+ const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
  const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
  const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
  as='h2'
  textVariant='h2'
  localizationKey={
- totals.totalDueNow.amount > 0
- ? localizationKeys('commerce.checkout.title__paymentSuccessful')
- : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+ freeTrialEndsAt
+ ? localizationKeys('commerce.checkout.title__trialSuccess')
+ : totals.totalDueNow.amount > 0
+ ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+ : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
  }
  sx={t => ({
  opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
  <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
  </LineItems.Group>
+
+ {freeTrialEndsAt ? (
+ <LineItems.Group variant='secondary'>
+ <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+ <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+ </LineItems.Group>
+ ) : null}
  <LineItems.Group variant='secondary'>
  <LineItems.Title
  title={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
  : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
  }
  />
  <LineItems.Description
  text={
- totals.totalDueNow.amount > 0
+ totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
  ? paymentSource
  ? paymentSource.paymentMethod !== 'card'
  ? `${capitalize(paymentSource.paymentMethod)}`

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
  const { checkout } = useCheckout();
 
- const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+ const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
  if (!id) {
  return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Title
  title={plan.name}
  description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+ badge={
+ plan.freeTrialEnabled && freeTrialEndsAt ? (
+ <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+ ) : null
+ }
  />
  <LineItems.Description
  prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
  <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
  </LineItems.Group>
  )}
+
+ {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+ <LineItems.Group variant='tertiary'>
+ <LineItems.Title
+ title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+ days: plan.freeTrialDays,
+ })}
+ />
+ <LineItems.Description
+ text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+ />
+ </LineItems.Group>
+ )}
+
  <LineItems.Group borderTop>
  <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
  <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
  );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
- const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
  const { checkout } = useCheckout();
- const { status, totals } = checkout;
+ const { status, freeTrialEndsAt, totals } = checkout;
 
  if (status === 'needs_initialization') {
- return null;
+ throw new Error('Clerk: Invalid state');
+ }
+
+ if (freeTrialEndsAt) {
+ return localizationKeys('commerce.startFreeTrial');
  }
 
+ if (totals.totalDueNow.amount > 0) {
+ return localizationKeys('commerce.pay', {
+ amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+ });
+ }
+
+ return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+ const { addPaymentSourceAndPay } = useCheckoutMutations();
+ const submitLabel = useSubmitLabel();
+ const { checkout } = useCheckout();
+
  return (
  <AddPaymentSource.Root
  onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
  <PayWithTestPaymentSource />
  </DevOnly>
 
- {totals.totalDueNow.amount > 0 ? (
- <AddPaymentSource.FormButton
- text={localizationKeys('commerce.pay', {
- amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
- })}
- />
- ) : (
- <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
- )}
+ <AddPaymentSource.FormButton text={submitLabel} />
  </AddPaymentSource.Root>
  );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  totalDueNow: CommerceMoneyAmount;
  paymentSources: CommercePaymentSourceResource[];
  }) => {
+ const submitLabel = useSubmitLabel();
  const { checkout } = useCheckout();
- const { paymentSource } = checkout;
+ const { paymentSource, freeTrialEndsAt } = checkout;
 
  const { payWithExistingPaymentSource } = useCheckoutMutations();
  const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  });
  }, [paymentSources]);
 
+ const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
  return (
  <Form
  onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  rowGap: t.space.$4,
  })}
  >
- {totalDueNow.amount > 0 ? (
+ {isSchedulePayment ? (
  <Select
  elementId='paymentSource'
  options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
  width: '100%',
  }}
  isLoading={card.isLoading}
- >
- <Text
- localizationKey={
- totalDueNow.amount > 0
- ? localizationKeys('commerce.pay', {
- amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
- })
- : localizationKeys('commerce.subscribe')
- }
- />
- </Button>
+ localizationKey={submitLabel}
+ />
  </Form>
  );
  },