chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
panteliselef merged 15 commits into from
Jul 23, 2025
Merged

chore(clerk-js,shared): Expose experimental useSubscription#6317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
c3c11f0
chore(clerk-js,shared): Expose experimental `useSubscription`
panteliselef Jul 15, 2025
9e5b3f8
Merge branch 'main' into elef/com-959-useSubscription
panteliselef Jul 16, 2025
238ebd1
bring back deleted apis
panteliselef Jul 16, 2025
791a6d7
update `useSubscription` with a strict interface
panteliselef Jul 16, 2025
dab66c5
update unit tests with mocked data
panteliselef Jul 16, 2025
2b36c62
leverage `undefined` next_payment
panteliselef Jul 16, 2025
ca0ecb6
Merge branch 'main' into elef/com-959-useSubscription
panteliselef Jul 16, 2025
c8242f7
update types
panteliselef Jul 21, 2025
08b3196
Merge branch 'refs/heads/main' into elef/com-959-useSubscription
panteliselef Jul 21, 2025
c0c8c89
patch
panteliselef Jul 21, 2025
8c524ac
Merge branch 'refs/heads/main' into elef/com-959-useSubscription
panteliselef Jul 22, 2025
e3610b2
handle rabbit feedback
panteliselef Jul 22, 2025
8e1c9e6
changeset
panteliselef Jul 22, 2025
c0bbd77
add description
panteliselef Jul 22, 2025
b8af083
patch things
panteliselef Jul 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/rare-readers-cough.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`.
6 changes: 6 additions & 0 deletions .changeset/wide-loops-decide.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.
3 changes: 3 additions & 0 deletions .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"types/commerce-statement-status.mdx",
"types/commerce-statement-totals-json.mdx",
"types/commerce-statement-totals.mdx",
"types/commerce-subscription-item-json.mdx",
"types/commerce-subscription-item-resource.mdx",
"types/commerce-subscription-json.mdx",
"types/commerce-subscription-plan-period.mdx",
"types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"types/get-payment-sources-params.mdx",
"types/get-plans-params.mdx",
"types/get-statements-params.mdx",
"types/get-subscription-params.mdx",
"types/get-subscriptions-params.mdx",
"types/get-token.mdx",
"types/id-selectors.mdx",
Expand Down
18 changes: 15 additions & 3 deletions packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
CommercePlanResource,
CommerceStatementJSON,
CommerceStatementResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CreateCheckoutParams,
GetPaymentAttemptsParams,
GetPlansParams,
GetStatementsParams,
GetSubscriptionParams,
GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
CommercePlan,
CommerceStatement,
CommerceSubscription,
CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
});
};

// Inconsistent API
getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
const plan = (await BaseResource._fetch({
path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
return new CommercePlan(plan);
};

getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
return await BaseResource._fetch({
path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
method: 'GET',
}).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
};

getSubscriptions = async (
params: GetSubscriptionsParams,
): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
const { orgId, ...rest } = params;

return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
search: convertPageToOffsetSearchParams(rest),
}).then(res => {
const { data: subscriptions, total_count } =
res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

return {
total_count,
data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
};
});
};
Expand Down
17 changes: 11 additions & 6 deletions packages/clerk-js/src/core/resources/CommercePayment.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
CommercePaymentChargeType,
CommercePaymentJSON,
CommercePaymentResource,
CommercePaymentSourceResource,
CommercePaymentStatus,
CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
id!: string;
amount!: CommerceMoney;
failedAt?: Date;
paidAt?: Date;
updatedAt!: Date;
paymentSource!: CommercePaymentSource;
subscription!: CommerceSubscription;
subscriptionItem!: CommerceSubscription;
paymentSource!: CommercePaymentSourceResource;
/**
* @deprecated
*/
subscription!: CommerceSubscriptionItemResource;
subscriptionItem!: CommerceSubscriptionItemResource;
chargeType!: CommercePaymentChargeType;
status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
this.updatedAt = unixEpochToDate(data.updated_at);
this.paymentSource = new CommercePaymentSource(data.payment_source);
this.subscription = new CommerceSubscription(data.subscription);
this.subscriptionItem = new CommerceSubscription(data.subscription_item);
this.subscription = new CommerceSubscriptionItem(data.subscription);
this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
this.chargeType = data.charge_type;
this.status = data.status;
return this;
Expand Down
47 changes: 45 additions & 2 deletions packages/clerk-js/src/core/resources/CommerceSubscription.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
CancelSubscriptionParams,
CommerceMoney,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
CommerceSubscriptionJSON,
CommerceSubscriptionPlanPeriod,
CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
id!: string;
status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
activeAt!: Date;
createdAt!: Date;
pastDueAt!: Date | null;
updatedAt!: Date | null;
nextPayment: {
amount: CommerceMoney;
date: Date;
} | null = null;
subscriptionItems!: CommerceSubscriptionItemResource[];

constructor(data: CommerceSubscriptionJSON) {
super();
this.fromJSON(data);
}

protected fromJSON(data: CommerceSubscriptionJSON | null): this {
if (!data) {
return this;
}

this.id = data.id;
this.status = data.status;
this.createdAt = unixEpochToDate(data.created_at);
this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
this.activeAt = unixEpochToDate(data.active_at);
this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
this.nextPayment = data.next_payment
? {
amount: commerceMoneyFromJSON(data.next_payment.amount),
date: unixEpochToDate(data.next_payment.date),
}
: null;
this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.
return this;
}
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
id!: string;
paymentSourceId!: string;
plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
periodStart!: number;
periodEnd!: number;
canceledAt!: number | null;
//TODO(@COMMERCE): Why can this be undefined ?

@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Address TODO comment about undefined amount

The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.

🏁 Script executed:

#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts

Length of output: 140215

🏁 Script executed:

#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts

Length of output: 3948

🏁 Script executed:

#!/bin/bash# List immediate subdirectories under packages
ls -1 packages

Length of output: 234

🏁 Script executed:

#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types

Length of output: 325

🏁 Script executed:

#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts

Length of output: 2839

Remove TODO and document optional amount

The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

amount?: CommerceMoney;
credit?: {
amount: CommerceMoney;
};

constructor(data: CommerceSubscriptionJSON) {
constructor(data: CommerceSubscriptionItemJSON) {
super();
this.fromJSON(data);
}

protected fromJSON(data: CommerceSubscriptionJSON | null): this {
protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
if (!data) {
return this;
}
Expand Down
12 changes: 6 additions & 6 deletions packages/clerk-js/src/core/resources/Organization.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
AddMemberParams,
ClerkPaginatedResponse,
ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
CreateOrganizationParams,
GetDomainsParams,
GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

getSubscriptions = async (
getSubscriptionsParams?: GetSubscriptionsParams,
): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
return await BaseResource._fetch({
path: `/organizations/${this.id}/commerce/subscriptions`,
method: 'GET',
search: convertPageToOffsetSearchParams(getSubscriptionsParams),
}).then(res => {
const { data: subscriptions, total_count } =
res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

return {
total_count,
data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
};
});
};
Expand Down
13 changes: 7 additions & 6 deletions packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
const clerk = useClerk();
const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
const isCompact = mode === 'modal';
const { data: subscriptions } = useSubscriptions();
const { subscriptionItems } = useSubscription();
const { data: plans } = usePlans();
const { handleSelectPlan } = usePlansContext();

const defaultPlanPeriod = useMemo(() => {
if (isCompact) {
const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
if (upcomingSubscription) {
return upcomingSubscription.planPeriod;
}

// don't pay attention to the default plan
const activeSubscription = subscriptions?.find(
const activeSubscription = subscriptionItems?.find(
sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
);
if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
}

return 'annual';
}, [isCompact, subscriptions]);
}, [isCompact, subscriptionItems]);

const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
chore(clerk-js,shared): Expose experimental useSubscription#6317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

panteliselef
merged 15 commits into

from

Jul 23, 2025
 Merged


chore(clerk-js,shared): Expose experimental useSubscription#6317
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


15 commits


Select commit
Hold shift + click to select a range
c3c11f0

chore(clerk-js,shared): Expose experimental `useSubscription`


panteliselef Jul 15, 2025
9e5b3f8

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
238ebd1

bring back deleted apis


panteliselef Jul 16, 2025
791a6d7

update `useSubscription` with a strict interface


panteliselef Jul 16, 2025
dab66c5

update unit tests with mocked data


panteliselef Jul 16, 2025
2b36c62

leverage `undefined` next_payment


panteliselef Jul 16, 2025
ca0ecb6

Merge branch 'main' into elef/com-959-useSubscription


panteliselef Jul 16, 2025
c8242f7

update types


panteliselef Jul 21, 2025
08b3196

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 21, 2025
c0c8c89

patch


panteliselef Jul 21, 2025
8c524ac

Merge branch 'refs/heads/main' into elef/com-959-useSubscription


panteliselef Jul 22, 2025
e3610b2

handle rabbit feedback


panteliselef Jul 22, 2025
8e1c9e6

changeset


panteliselef Jul 22, 2025
c0bbd77

add description


panteliselef Jul 22, 2025
b8af083

patch things


panteliselef Jul 23, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 9 additions & 0 deletions
.changeset/rare-readers-cough.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
---

[Billing Beta] Introduce top level subscription.

Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

6 changes: 6 additions & 0 deletions
.changeset/wide-loops-decide.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

3 changes: 3 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/commerce-statement-status.mdx",
 "types/commerce-statement-totals-json.mdx",
 "types/commerce-statement-totals.mdx",
 "types/commerce-subscription-item-json.mdx",
 "types/commerce-subscription-item-resource.mdx",
 "types/commerce-subscription-json.mdx",
 "types/commerce-subscription-plan-period.mdx",
 "types/commerce-subscription-resource.mdx",
Expand All@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "types/get-payment-sources-params.mdx",
 "types/get-plans-params.mdx",
 "types/get-statements-params.mdx",
 "types/get-subscription-params.mdx",
 "types/get-subscriptions-params.mdx",
 "types/get-token.mdx",
 "types/id-selectors.mdx",
Expand Down

18 changes: 15 additions & 3 deletions
packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -8,12 +8,15 @@ import type {
 CommercePlanResource,
 CommerceStatementJSON,
 CommerceStatementResource,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionResource,
 CreateCheckoutParams,
 GetPaymentAttemptsParams,
 GetPlansParams,
 GetStatementsParams,
 GetSubscriptionParams,
 GetSubscriptionsParams,
} from '@clerk/types';

Expand All@@ -25,6 +28,7 @@ import {
 CommercePlan,
 CommerceStatement,
 CommerceSubscription,
 CommerceSubscriptionItem,
} from '../../resources/internal';

export class CommerceBilling implements CommerceBillingNamespace {
Expand All@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
 });
 };

 // Inconsistent API
 getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
 const plan = (await BaseResource._fetch({
 path: `/commerce/plans/${params.id}`,
Expand All@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
 return new CommercePlan(plan);
 };

 getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
 return await BaseResource._fetch({
 path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
 method: 'GET',
 }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
 };

 getSubscriptions = async (
 params: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 const { orgId, ...rest } = params;

 return await BaseResource._fetch({
Expand All@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
 search: convertPageToOffsetSearchParams(rest),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

17 changes: 11 additions & 6 deletions
packages/clerk-js/src/core/resources/CommercePayment.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,22 +3,27 @@ import type {
 CommercePaymentChargeType,
 CommercePaymentJSON,
 CommercePaymentResource,
 CommercePaymentSourceResource,
 CommercePaymentStatus,
 CommerceSubscriptionItemResource,
} from '@clerk/types';

import { commerceMoneyFromJSON } from '../../utils';
import { unixEpochToDate } from '../../utils/date';
import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';

export class CommercePayment extends BaseResource implements CommercePaymentResource {
 id!: string;
 amount!: CommerceMoney;
 failedAt?: Date;
 paidAt?: Date;
 updatedAt!: Date;
 paymentSource!: CommercePaymentSource;
 subscription!: CommerceSubscription;
 subscriptionItem!: CommerceSubscription;
 paymentSource!: CommercePaymentSourceResource;
 /**
 * @deprecated
 */
 subscription!: CommerceSubscriptionItemResource;
 subscriptionItem!: CommerceSubscriptionItemResource;
 chargeType!: CommercePaymentChargeType;
 status!: CommercePaymentStatus;

Expand All@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
 this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
 this.updatedAt = unixEpochToDate(data.updated_at);
 this.paymentSource = new CommercePaymentSource(data.payment_source);
 this.subscription = new CommerceSubscription(data.subscription);
 this.subscriptionItem = new CommerceSubscription(data.subscription_item);
 this.subscription = new CommerceSubscriptionItem(data.subscription);
 this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
 this.chargeType = data.charge_type;
 this.status = data.status;
 return this;
Expand Down

47 changes: 45 additions & 2 deletions
packages/clerk-js/src/core/resources/CommerceSubscription.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
import type {
 CancelSubscriptionParams,
 CommerceMoney,
 CommerceSubscriptionItemJSON,
 CommerceSubscriptionItemResource,
 CommerceSubscriptionJSON,
 CommerceSubscriptionPlanPeriod,
 CommerceSubscriptionResource,
Expand All@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
import { BaseResource, CommercePlan, DeletedObject } from './internal';

export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
 id!: string;
 status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
 activeAt!: Date;
 createdAt!: Date;
 pastDueAt!: Date | null;
 updatedAt!: Date | null;
 nextPayment: {
 amount: CommerceMoney;
 date: Date;
 } | null = null;
 subscriptionItems!: CommerceSubscriptionItemResource[];

 constructor(data: CommerceSubscriptionJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 if (!data) {
 return this;
 }

 this.id = data.id;
 this.status = data.status;
 this.createdAt = unixEpochToDate(data.created_at);
 this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
 this.activeAt = unixEpochToDate(data.active_at);
 this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
 this.nextPayment = data.next_payment
 ? {
 amount: commerceMoneyFromJSON(data.next_payment.amount),
 date: unixEpochToDate(data.next_payment.date),
 }
 : null;
 this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
Comment thread
panteliselef marked this conversation as resolved.

 return this;
 }
}

export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
 id!: string;
 paymentSourceId!: string;
 plan!: CommercePlan;
Expand All@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
 periodStart!: number;
 periodEnd!: number;
 canceledAt!: number | null;
 //TODO(@COMMERCE): Why can this be undefined ?
@coderabbitaicoderabbitaiBotJul 21, 2025

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent
🧩 Analysis chain
Address TODO comment about undefined amount
The TODO raises a valid concern about why amount can be undefined. This should be investigated and resolved.
🏁 Script executed:
#!/bin/bash# Search for usage of CommerceSubscriptionItem to understand when amount might be undefined
ast-grep --pattern 'amount'| rg -B5 -A5 "CommerceSubscriptionItem"# Check if there are any subscription items without amount in the codebase
rg -A10 "amount.*undefined|amount.*null" --type ts
Length of output: 140215
🏁 Script executed:
#!/bin/bash# Display the first 200 lines of CommerceSubscription.ts to inspect the class signature and constructor
sed -n '1,200p' packages/clerk-js/src/core/resources/CommerceSubscription.ts
Length of output: 3948
🏁 Script executed:
#!/bin/bash# List immediate subdirectories under packages
ls -1 packages
Length of output: 234
🏁 Script executed:
#!/bin/bash# List files in the types package
ls -1 packages/types
# Search for CommerceSubscriptionItemJSON in the types definitions
rg -n "export interface CommerceSubscriptionItemJSON" -n packages/types
Length of output: 325
🏁 Script executed:
#!/bin/bash# Show CommerceSubscriptionItemJSON interface definition
sed -n '760,840p' packages/types/src/json.ts
Length of output: 2839
Remove TODO and document optional amount
The CommerceSubscriptionItemJSON.amount field is defined as optional in the API types (amount?: CommerceMoneyJSON), so it can legitimately be undefined (for example, on free‐plan or credit‐only subscription items). Remove the TODO and replace it with a clear explanatory comment:
export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
// …
- //TODO(@COMMERCE): Why can this be undefined ?+ // `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
amount?: CommerceMoney;
// …
}
📝 Committable suggestion
‼️IMPORTANT

Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

//TODO(@COMMERCE): Why can this be undefined ?
exportclassCommerceSubscriptionItemextendsBaseResourceimplementsCommerceSubscriptionItemResource{
// …
// `amount` is optional per API spec (e.g., free‐plan or credit‐only items)
 amount?: CommerceMoney;
// …
}
🤖 Prompt for AI Agents
In packages/clerk-js/src/core/resources/CommerceSubscription.ts at line 72,
remove the TODO comment questioning why the amount can be undefined. Instead,
add a clear comment explaining that the CommerceSubscriptionItemJSON.amount
field is optional as per the API types and can be undefined for cases like
free-plan or credit-only subscription items.

 amount?: CommerceMoney;
 credit?: {
 amount: CommerceMoney;
 };

 constructor(data: CommerceSubscriptionJSON) {
 constructor(data: CommerceSubscriptionItemJSON) {
 super();
 this.fromJSON(data);
 }

 protected fromJSON(data: CommerceSubscriptionJSON | null): this {
 protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
 if (!data) {
 return this;
 }
Expand Down

12 changes: 6 additions & 6 deletions
packages/clerk-js/src/core/resources/Organization.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,8 @@ import type {
 AddMemberParams,
 ClerkPaginatedResponse,
 ClerkResourceReloadParams,
CommerceSubscriptionJSON,
CommerceSubscriptionResource,
CommerceSubscriptionItemJSON,
CommerceSubscriptionItemResource,
 CreateOrganizationParams,
 GetDomainsParams,
 GetInvitationsParams,
Expand DownExpand Up@@ -32,7 +32,7 @@ import type {
import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
import { unixEpochToDate } from '../../utils/date';
import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
import { OrganizationDomain } from './OrganizationDomain';
import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
import { Role } from './Role';
Expand DownExpand Up@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {

 getSubscriptions = async (
 getSubscriptionsParams?: GetSubscriptionsParams,
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
 ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
 return await BaseResource._fetch({
 path: `/organizations/${this.id}/commerce/subscriptions`,
 method: 'GET',
 search: convertPageToOffsetSearchParams(getSubscriptionsParams),
 }).then(res => {
 const { data: subscriptions, total_count } =
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
 res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;

 return {
 total_count,
 data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
 data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
 };
 });
 };
Expand Down

13 changes: 7 additions & 6 deletions
packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
import { useEffect, useMemo, useState } from 'react';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
import { Flow } from '../../customizables';
import { Flow } from '@/ui/customizables/Flow';

import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
import { PricingTableDefault } from './PricingTableDefault';
import { PricingTableMatrix } from './PricingTableMatrix';

const PricingTableRoot = (props: PricingTableProps) => {
 const clerk = useClerk();
 const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
 const isCompact = mode === 'modal';
 const { data: subscriptions } = useSubscriptions();
 const { subscriptionItems } = useSubscription();
 const { data: plans } = usePlans();
 const { handleSelectPlan } = usePlansContext();

 const defaultPlanPeriod = useMemo(() => {
 if (isCompact) {
 const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
 const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
 if (upcomingSubscription) {
 return upcomingSubscription.planPeriod;
 }

 // don't pay attention to the default plan
 const activeSubscription = subscriptions?.find(
 const activeSubscription = subscriptionItems?.find(
 sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
 );
 if (activeSubscription) {
Expand All@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
 }

 return 'annual';
 }, [isCompact, subscriptions]);
 }, [isCompact, subscriptionItems]);

 const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);

Expand Down
Loading