Skip to content

chore(clerk-js,types): Replace commerce with billing in resources #6757

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
merged 7 commits into from
Sep 18, 2025
Merged

chore(clerk-js,types): Replace commerce with billing in resources #6757

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
dd915af
chore(clerk-js,types): Replace commerce with billing in resources
panteliselef Sep 11, 2025
a0a88ad
fix tests
panteliselef Sep 11, 2025
2dcdae6
patch test
panteliselef Sep 15, 2025
999155f
update typedocs
panteliselef Sep 16, 2025
08afc8b
Merge branch 'main' into elef/bill-1249-rename-types-for-commerce-to-…
alexisintech Sep 17, 2025
f3a3a67
add missing field
panteliselef Sep 18, 2025
f4bdbed
Merge branch 'main' into elef/bill-1249-rename-types-for-commerce-to-…
panteliselef Sep 18, 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/yummy-snails-work.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@clerk/clerk-js': minor
'@clerk/types': minor
'@clerk/backend': patch
'@clerk/shared': patch
Comment on lines +2 to +5
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

Semver levels likely incorrect for public API/type renames — should be major.

Renaming exported types/classes from Commerce* → Billing* is a breaking change for consumers. Unless you ship full backwards-compatible aliases for all renamed public exports (and keep them in the public surface), bump these packages to major to avoid releasing a breaking change under minor/patch.

Apply this diff if there are breaking changes:

-'@clerk/clerk-js': minor
-'@clerk/types': minor
-'@clerk/backend': patch
-'@clerk/shared': patch
+'@clerk/clerk-js': major
+'@clerk/types': major
+'@clerk/backend': major
+'@clerk/shared': major

If you do have deprecation aliases covering all renamed exports, keep minor but explicitly state that in the description (see next comment).

📝 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
'@clerk/clerk-js': minor
'@clerk/types': minor
'@clerk/backend': patch
'@clerk/shared': patch
'@clerk/clerk-js': major
'@clerk/types': major
'@clerk/backend': major
'@clerk/shared': major
🤖 Prompt for AI Agents 
.changeset/yummy-snails-work.md around lines 2 to 5: The changeset lists
minor/patch bumps for packages where exported types/classes were renamed from
Commerce* to Billing*, which is a breaking API change for consumers; either
change the version bumps to major for any package that removed/renamed public
exports, or add and keep backwards-compatible aliases (exporting the old
Commerce* names re-exporting the new Billing* symbols) in the public surface so
the change truly remains non-breaking; update the changeset to use major for the
affected packages unless you add comprehensive deprecation aliases and then
document that in the changeset description.

Copy link
Member

Choose a reason for hiding this comment

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

These types are internal

Copy link
Contributor

Choose a reason for hiding this comment

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

🧩 Analysis chain

I need to verify whether these Commerce* → Billing* types are truly internal or part of the public API surface.

🏁 Script executed:

#!/bin/bash
# Check what's exported from @clerk/types package
echo "=== Checking @clerk/types exports ==="
fd -t f "index" packages/types/src --exec cat {} \; | head -50

echo -e "\n=== Searching for Commerce*/Billing* exports in types package ==="
rg -n "export.*Commerce|export.*Billing" packages/types/src/ | head -20

echo -e "\n=== Checking if Commerce types were exported in clerk.ts ==="
rg -n -A3 -B3 "Commerce.*Namespace|Billing.*Namespace" packages/types/src/clerk.ts

echo -e "\n=== Checking commerce.ts exports ==="
rg -n "export" packages/types/src/commerce.ts | head -10

Length of output: 4768

🏁 Script executed:

#!/bin/bash
# Check if any Commerce types still exist in the exports
echo "=== Checking for remaining Commerce* exports ==="
rg -n "export.*Commerce" packages/types/src/

echo -e "\n=== Checking what was actually removed/renamed ==="
echo "Looking for Commerce types in the previous version that might have been public..."

echo -e "\n=== Check if there are any re-exports or aliases for backwards compatibility ==="
rg -n "Commerce.*=" packages/types/src/ | head -10

echo -e "\n=== Check public API usage in other packages to see if these were truly internal ==="
rg -n "import.*Commerce.*from.*@clerk/types" packages/clerk-js/src/ packages/shared/src/ packages/react/src/ | head -10

echo -e "\n=== Check for any backwards compatibility aliases ==="
rg -n -B2 -A2 "Commerce.*Billing|Billing.*Commerce" packages/types/src/

Length of output: 995

🏁 Script executed:

#!/bin/bash
# Let's check what types were actually being imported and used across packages before the change
echo "=== Check how Commerce types were used in clerk-js package ==="
rg -n "Commerce.*Resource|Commerce.*JSON" packages/clerk-js/src/ | head -15

echo -e "\n=== Check what's imported in the test files to understand public vs internal ==="
rg -n "import.*type.*{.*Commerce" packages/clerk-js/src/ packages/shared/src/ packages/react/src/ | head -10

echo -e "\n=== Check the main Clerk interface definition for billing ==="
cat packages/types/src/clerk.ts | grep -A5 -B5 "billing.*:"

echo -e "\n=== Check if the old Commerce types were part of the main Clerk export ==="
rg -n "CommerceBillingNamespace" packages/types/src/clerk.ts || echo "Not found in current version"

Length of output: 2013

🏁 Script executed:

#!/bin/bash
# Fix the regex and check imports properly
echo "=== Check what's imported in test/source files ==="
rg -n "import.*type.*Commerce" packages/clerk-js/src/ packages/shared/src/ packages/react/src/ | head -10

echo -e "\n=== Look at the package.json exports to see what's actually exposed ==="
cat packages/types/package.json | grep -A20 -B5 '"exports"' || echo "No exports field found"

echo -e "\n=== Check if these types were meant to be used by consumers ==="
echo "Looking at how billing namespace is used in clerk-js..."
rg -n -B2 -A2 "BillingNamespace|CommerceBillingNamespace" packages/clerk-js/src/

echo -e "\n=== Check what files were actually changed in this PR ==="
echo "Based on the AI summary, many files show 'public entities' being changed..."
echo "Let's verify if billing types are part of the main API surface"
rg -n "billing.*:" packages/types/src/clerk.ts

Length of output: 2699

@wobsoriano, I understand your point, but I need to respectfully disagree based on the evidence from the codebase.

The evidence shows these types are part of the public API:

  1. Public exports: The types are exported from @clerk/types via export * from './commerce' in the main index file
  2. Main Clerk interface: BillingNamespace is exposed as billing: BillingNamespace in the core Clerk interface in packages/types/src/clerk.ts
  3. Cross-package usage: These types are imported and used across @clerk/clerk-js, @clerk/shared, and @clerk/react packages
  4. Consumer-facing API: The clerk.billing.* methods return these resources, making them part of the public surface

The AI summary confirms multiple "Alterations to the declarations of exported or public entities" including:

  • CommerceBillingNamespace → BillingNamespace
  • CommerceCheckoutResource → BillingCheckoutResource
  • CommercePlanResource → BillingPlanResource
  • And many others exported from the packages

If these were truly internal, they wouldn't be:

  • Exported from the main package index
  • Part of the core Clerk interface
  • Used as return types for public clerk.billing.* methods

This is a breaking change requiring major version bumps for the affected packages, unless you add backwards-compatible aliases for all the renamed exports.

🐰💭

✏️ Learnings added 
Learnt from: wobsoriano
PR: clerk/javascript#6757
File: .changeset/yummy-snails-work.md:2-5
Timestamp: 2025-09-15T15:35:31.013Z
Learning: Types exported from clerk/types through export * from module files and used in the main Clerk interface (like BillingNamespace in clerk.billing) are part of the public API surface, even if the maintainer considers them "internal". Breaking changes to exported types require major version bumps unless backwards-compatible aliases are provided.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

'@clerk/clerk-react': patch
---

[Billing Beta] Rename types, interfaces and classes that contain `commerce` to use `billing` instead.
74 changes: 37 additions & 37 deletions .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,41 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"types/act-jwt-claim.mdx",
"types/active-session-resource.mdx",
"types/add-payment-source-params.mdx",
"types/billing-checkout-json.mdx",
"types/billing-checkout-resource.mdx",
"types/billing-checkout-totals-json.mdx",
"types/billing-checkout-totals.mdx",
"types/billing-initialized-payment-source-json.mdx",
"types/billing-initialized-payment-source-resource.mdx",
"types/billing-money-amount-json.mdx",
"types/billing-money-amount.mdx",
"types/billing-namespace.mdx",
"types/billing-payer-json.mdx",
"types/billing-payer-resource-type.mdx",
"types/billing-payer-resource.mdx",
"types/billing-payment-charge-type.mdx",
"types/billing-payment-json.mdx",
"types/billing-payment-resource.mdx",
"types/billing-payment-source-json.mdx",
"types/billing-payment-source-methods.mdx",
"types/billing-payment-source-resource.mdx",
"types/billing-payment-source-status.mdx",
"types/billing-payment-status.mdx",
"types/billing-plan-json.mdx",
"types/billing-plan-resource.mdx",
"types/billing-statement-group-json.mdx",
"types/billing-statement-group.mdx",
"types/billing-statement-json.mdx",
"types/billing-statement-resource.mdx",
"types/billing-statement-status.mdx",
"types/billing-statement-totals-json.mdx",
"types/billing-statement-totals.mdx",
"types/billing-subscription-item-json.mdx",
"types/billing-subscription-item-resource.mdx",
"types/billing-subscription-json.mdx",
"types/billing-subscription-plan-period.mdx",
"types/billing-subscription-resource.mdx",
"types/billing-subscription-status.mdx",
"types/cancel-subscription-params.mdx",
"types/check-authorization-fn.mdx",
"types/check-authorization-from-session-claims.mdx",
Expand All @@ -21,43 +56,6 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"types/clerk-resource.mdx",
"types/clerk-status.mdx",
"types/clerk.mdx",
"types/commerce-billing-namespace.mdx",
"types/commerce-checkout-json.mdx",
"types/commerce-checkout-resource.mdx",
"types/commerce-checkout-totals-json.mdx",
"types/commerce-checkout-totals.mdx",
"types/commerce-feature-json.mdx",
"types/commerce-feature-resource.mdx",
"types/commerce-initialized-payment-source-json.mdx",
"types/commerce-initialized-payment-source-resource.mdx",
"types/commerce-money-amount-json.mdx",
"types/commerce-money-amount.mdx",
"types/commerce-payer-json.mdx",
"types/commerce-payer-resource-type.mdx",
"types/commerce-payer-resource.mdx",
"types/commerce-payment-charge-type.mdx",
"types/commerce-payment-json.mdx",
"types/commerce-payment-resource.mdx",
"types/commerce-payment-source-json.mdx",
"types/commerce-payment-source-methods.mdx",
"types/commerce-payment-source-resource.mdx",
"types/commerce-payment-source-status.mdx",
"types/commerce-payment-status.mdx",
"types/commerce-plan-json.mdx",
"types/commerce-plan-resource.mdx",
"types/commerce-statement-group-json.mdx",
"types/commerce-statement-group.mdx",
"types/commerce-statement-json.mdx",
"types/commerce-statement-resource.mdx",
"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",
"types/commerce-subscription-status.mdx",
"types/confirm-checkout-params.mdx",
"types/create-checkout-params.mdx",
"types/create-organization-params.mdx",
Expand All @@ -67,6 +65,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"types/experimental_checkout-button-props.mdx",
"types/experimental_plan-details-button-props.mdx",
"types/experimental_subscription-details-button-props.mdx",
"types/feature-json.mdx",
"types/feature-resource.mdx",
"types/field-error.mdx",
"types/field-errors.mdx",
"types/for-payer-type.mdx",
Expand Down
8 changes: 4 additions & 4 deletions packages/backend/src/api/resources/CommercePlan.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { CommerceMoneyAmount } from '@clerk/types';
import type { BillingMoneyAmount } from '@clerk/types';

import { Feature } from './Feature';
import type { CommercePlanJSON } from './JSON';
Expand Down Expand Up @@ -49,15 +49,15 @@ export class CommercePlan {
/**
* The monthly fee of the plan.
*/
readonly fee: CommerceMoneyAmount,
readonly fee: BillingMoneyAmount,
/**
* The annual fee of the plan.
*/
readonly annualFee: CommerceMoneyAmount,
readonly annualFee: BillingMoneyAmount,
/**
* The annual fee of the plan on a monthly basis.
*/
readonly annualMonthlyFee: CommerceMoneyAmount,
readonly annualMonthlyFee: BillingMoneyAmount,
/**
* The type of payer for the plan.
*/
Expand Down
4 changes: 2 additions & 2 deletions packages/backend/src/api/resources/CommerceSubscription.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { type CommerceMoneyAmount } from '@clerk/types';
import { type BillingMoneyAmount } from '@clerk/types';

import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
import type { CommerceSubscriptionJSON } from './JSON';
Expand Down Expand Up @@ -45,7 +45,7 @@ export class CommerceSubscription {
/**
* Information about the next scheduled payment.
*/
readonly nextPayment: { date: number; amount: CommerceMoneyAmount } | null,
readonly nextPayment: { date: number; amount: BillingMoneyAmount } | null,
/**
* Whether the payer is eligible for a free trial.
*/
Expand Down
10 changes: 5 additions & 5 deletions packages/backend/src/api/resources/CommerceSubscriptionItem.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { CommerceMoneyAmount, CommerceMoneyAmountJSON } from '@clerk/types';
import type { BillingMoneyAmount, BillingMoneyAmountJSON } from '@clerk/types';

import { CommercePlan } from './CommercePlan';
import type { CommerceSubscriptionItemJSON } from './JSON';
Expand Down Expand Up @@ -42,7 +42,7 @@ export class CommerceSubscriptionItem {
/**
* The current amount for the subscription item.
*/
readonly amount: CommerceMoneyAmount | null | undefined,
readonly amount: BillingMoneyAmount | null | undefined,
/**
* The plan associated with this subscription item.
*/
Expand Down Expand Up @@ -86,13 +86,13 @@ export class CommerceSubscriptionItem {
/**
* The lifetime amount paid for this subscription item.
*/
readonly lifetimePaid?: CommerceMoneyAmount | null,
readonly lifetimePaid?: BillingMoneyAmount | null,
) {}

static fromJSON(data: CommerceSubscriptionItemJSON): CommerceSubscriptionItem {
function formatAmountJSON(
amount: CommerceMoneyAmountJSON | null | undefined,
): CommerceMoneyAmount | null | undefined {
amount: BillingMoneyAmountJSON | null | undefined,
): BillingMoneyAmount | null | undefined {
if (!amount) {
return amount;
}
Expand Down
16 changes: 8 additions & 8 deletions packages/clerk-js/src/core/clerk.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ import type {
AuthenticateWithGoogleOneTapParams,
AuthenticateWithMetamaskParams,
AuthenticateWithOKXWalletParams,
BillingNamespace,
Clerk as ClerkInterface,
ClerkAPIError,
ClerkAuthenticateWithWeb3Params,
ClerkOptions,
ClientJSONSnapshot,
ClientResource,
CommerceBillingNamespace,
CreateOrganizationParams,
CreateOrganizationProps,
CredentialReturn,
Expand Down Expand Up @@ -148,7 +148,7 @@ import { createFapiClient } from './fapiClient';
import { createClientFromJwt } from './jwt-client';
import { APIKeys } from './modules/apiKeys';
import { createCheckoutInstance } from './modules/checkout/instance';
import { CommerceBilling } from './modules/commerce';
import { Billing } from './modules/commerce';
import {
BaseResource,
Client,
Expand Down Expand Up @@ -206,7 +206,7 @@ export class Clerk implements ClerkInterface {
version: __PKG_VERSION__,
};

private static _billing: CommerceBillingNamespace;
private static _billing: BillingNamespace;
private static _apiKeys: APIKeysNamespace;
private _checkout: ClerkInterface['__experimental_checkout'] | undefined;

Expand Down Expand Up @@ -337,9 +337,9 @@ export class Clerk implements ClerkInterface {
return this.#options.standardBrowser || false;
}

get billing(): CommerceBillingNamespace {
get billing(): BillingNamespace {
if (!Clerk._billing) {
Clerk._billing = new CommerceBilling();
Clerk._billing = new Billing();
}
return Clerk._billing;
}
Expand Down Expand Up @@ -625,7 +625,7 @@ export class Clerk implements ClerkInterface {
this.assertComponentsReady(this.#componentControls);
if (disabledAllBillingFeatures(this, this.environment)) {
if (this.#instanceType === 'development') {
throw new ClerkRuntimeError(warnings.cannotRenderAnyCommerceComponent('Checkout'), {
throw new ClerkRuntimeError(warnings.cannotRenderAnyBillingComponent('Checkout'), {
code: CANNOT_RENDER_BILLING_DISABLED_ERROR_CODE,
});
}
Expand Down Expand Up @@ -654,7 +654,7 @@ export class Clerk implements ClerkInterface {
this.assertComponentsReady(this.#componentControls);
if (disabledAllBillingFeatures(this, this.environment)) {
if (this.#instanceType === 'development') {
throw new ClerkRuntimeError(warnings.cannotRenderAnyCommerceComponent('PlanDetails'), {
throw new ClerkRuntimeError(warnings.cannotRenderAnyBillingComponent('PlanDetails'), {
code: CANNOT_RENDER_BILLING_DISABLED_ERROR_CODE,
});
}
Expand Down Expand Up @@ -1113,7 +1113,7 @@ export class Clerk implements ClerkInterface {
this.assertComponentsReady(this.#componentControls);
if (disabledAllBillingFeatures(this, this.environment)) {
if (this.#instanceType === 'development') {
throw new ClerkRuntimeError(warnings.cannotRenderAnyCommerceComponent('PricingTable'), {
throw new ClerkRuntimeError(warnings.cannotRenderAnyBillingComponent('PricingTable'), {
code: CANNOT_RENDER_BILLING_DISABLED_ERROR_CODE,
});
}
Expand Down
Loading
Loading