Skip to content

chore(clerk-js,backend): Replace /commerce endpoints with /billing endpoints #6854

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 3 commits into from
Oct 15, 2025
+20 −20
Merged

chore(clerk-js,backend): Replace /commerce endpoints with /billing endpoints #6854

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3aa3a07
chore(clerk-js,backend): Replace `/commerce` endpoints with `/billing…
panteliselef Sep 25, 2025
c509060
fix
panteliselef Oct 10, 2025
f1b0098
Merge branch 'main' into elef/bill-1279-js-sdks-to-use-billing-path-i…
panteliselef Oct 15, 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
6 changes: 6 additions & 0 deletions .changeset/young-nails-matter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': patch
'@clerk/backend': patch
---

Replace `/commerce` endpoints with `/billing` endpoints.
2 changes: 1 addition & 1 deletion packages/backend/src/api/endpoints/BillingApi.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import type { BillingSubscriptionItem } from '../resources/CommerceSubscriptionI
import type { PaginatedResourceResponse } from '../resources/Deserializer';
import { AbstractAPI } from './AbstractApi';

const basePath = '/commerce';
const basePath = '/billing';
const organizationBasePath = '/organizations';
const userBasePath = '/users';

Expand Down
22 changes: 9 additions & 13 deletions packages/clerk-js/src/core/modules/billing/namespace.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import {
} from '../../resources/internal';

export class Billing implements BillingNamespace {
static readonly #pathRoot = '/commerce';
static readonly #pathRoot = '/billing';
static path(subPath: string, param?: { orgId?: string }): string {
const { orgId } = param || {};
const prefix = orgId ? `/organizations/${orgId}` : '/me';
Expand All @@ -39,7 +39,7 @@ export class Billing implements BillingNamespace {
const { for: forParam, ...safeParams } = params || {};
const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };
return await BaseResource._fetch({
path: `/commerce/plans`,
path: `${Billing.#pathRoot}/plans`,
Copy link
Member

Choose a reason for hiding this comment

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

🔧 Looks like this is calling an authenticated endpoint /me/billing/plans but the actual path is just /billing/plans

Copy link
Member Author

Choose a reason for hiding this comment

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

This should be fixed since I merged main into this branch. take a look here https://clerk-js-sandbox-gqfa0nbi0.clerkstage.dev/pricing-table

method: 'GET',
search: convertPageToOffsetSearchParams(searchParams),
}).then(res => {
Expand All @@ -55,15 +55,15 @@ export class Billing implements BillingNamespace {
// Inconsistent API
getPlan = async (params: { id: string }): Promise<BillingPlanResource> => {
const plan = (await BaseResource._fetch({
path: `/commerce/plans/${params.id}`,
path: `${Billing.#pathRoot}/plans/${params.id}`,
method: 'GET',
})) as unknown as BillingPlanJSON;
return new BillingPlan(plan);
};

getSubscription = async (params: GetSubscriptionParams): Promise<BillingSubscriptionResource> => {
return await BaseResource._fetch({
path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
path: Billing.path(`/subscription`, { orgId: params.orgId }),
method: 'GET',
}).then(res => new BillingSubscription(res?.response as BillingSubscriptionJSON));
};
Expand All @@ -72,7 +72,7 @@ export class Billing implements BillingNamespace {
const { orgId, ...rest } = params;

return await BaseResource._fetch({
path: orgId ? `/organizations/${orgId}/commerce/statements` : `/me/commerce/statements`,
path: Billing.path(`/statements`, { orgId }),
method: 'GET',
search: convertPageToOffsetSearchParams(rest),
}).then(res => {
Expand All @@ -89,9 +89,7 @@ export class Billing implements BillingNamespace {
getStatement = async (params: { id: string; orgId?: string }): Promise<BillingStatementResource> => {
const statement = (
await BaseResource._fetch({
path: params.orgId
? `/organizations/${params.orgId}/commerce/statements/${params.id}`
: `/me/commerce/statements/${params.id}`,
path: Billing.path(`/statements/${params.id}`, { orgId: params.orgId }),
method: 'GET',
})
)?.response as unknown as BillingStatementJSON;
Expand All @@ -104,7 +102,7 @@ export class Billing implements BillingNamespace {
const { orgId, ...rest } = params;

return await BaseResource._fetch({
path: orgId ? `/organizations/${orgId}/commerce/payment_attempts` : `/me/commerce/payment_attempts`,
path: Billing.path(`/payment_attempts`, { orgId }),
method: 'GET',
search: convertPageToOffsetSearchParams(rest),
}).then(res => {
Expand All @@ -119,9 +117,7 @@ export class Billing implements BillingNamespace {

getPaymentAttempt = async (params: { id: string; orgId?: string }): Promise<BillingPaymentResource> => {
const paymentAttempt = (await BaseResource._fetch({
path: params.orgId
? `/organizations/${params.orgId}/commerce/payment_attempts/${params.id}`
: `/me/commerce/payment_attempts/${params.id}`,
path: Billing.path(`/payment_attempts/${params.id}`, { orgId: params.orgId }),
method: 'GET',
})) as unknown as BillingPaymentJSON;
return new BillingPayment(paymentAttempt);
Expand All @@ -131,7 +127,7 @@ export class Billing implements BillingNamespace {
const { orgId, ...rest } = params;
const json = (
await BaseResource._fetch<BillingCheckoutJSON>({
path: orgId ? `/organizations/${orgId}/commerce/checkouts` : `/me/commerce/checkouts`,
path: Billing.path(`/checkouts`, { orgId }),
method: 'POST',
body: rest as any,
})
Expand Down
5 changes: 2 additions & 3 deletions packages/clerk-js/src/core/resources/BillingCheckout.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import type {
import { unixEpochToDate } from '@/utils/date';

import { billingTotalsFromJSON } from '../../utils';
import { Billing } from '../modules/billing/namespace';
import { BillingPayer } from './BillingPayer';
import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';

Expand Down Expand Up @@ -62,9 +63,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
return retry(
() =>
this._basePatch({
path: this.payer.organizationId
? `/organizations/${this.payer.organizationId}/commerce/checkouts/${this.id}/confirm`
: `/me/commerce/checkouts/${this.id}/confirm`,
path: Billing.path(`/checkouts/${this.id}/confirm`, { orgId: this.payer.organizationId }),
body: params as any,
}),
{
Expand Down
5 changes: 2 additions & 3 deletions packages/clerk-js/src/core/resources/BillingSubscription.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import type {
import { unixEpochToDate } from '@/utils/date';

import { billingMoneyAmountFromJSON } from '../../utils';
import { Billing } from '../modules/billing/namespace';
import { BaseResource, BillingPlan, DeletedObject } from './internal';

export class BillingSubscription extends BaseResource implements BillingSubscriptionResource {
Expand Down Expand Up @@ -110,9 +111,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
const { orgId } = params;
const json = (
await BaseResource._fetch({
path: orgId
? `/organizations/${orgId}/commerce/subscription_items/${this.id}`
: `/me/commerce/subscription_items/${this.id}`,
path: Billing.path(`/subscription_items/${this.id}`, { orgId }),
method: 'DELETE',
})
Comment on lines +114 to 116
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

Restore organization billing routes before merging

Line 114: Billing.path currently disregards orgId because the helper always overwrites the prefix with /me after the conditional assignment. As soon as this method is called for an organization subscription item, we’ll hit /me/billing/subscription_items/... instead of /organizations/${orgId}/billing/..., causing the cancel call to fail. Please fix the helper so it preserves the organization prefix.

 static path(subPath: string, param?: { orgId?: string }): string {
   const { orgId } = param || {};
-  let prefix = '';
-  if (orgId) {
-    prefix = `/organizations/${orgId}`;
-  }
-  prefix = '/me';
+  const prefix = orgId ? `/organizations/${orgId}` : '/me';
   return `${prefix}${Billing.#pathRoot}${subPath}`;
 }
📝 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
path: Billing.path(`/subscription_items/${this.id}`, { orgId }),
method: 'DELETE',
})
static path(subPath: string, param?: { orgId?: string }): string {
const { orgId } = param || {};
const prefix = orgId ? `/organizations/${orgId}` : '/me';
return `${prefix}${Billing.#pathRoot}${subPath}`;
}
🤖 Prompt for AI Agents 
In packages/clerk-js/src/core/resources/BillingSubscription.ts around lines
114-116, the call uses Billing.path(..., { orgId }) but the Billing.path helper
currently overwrites the computed prefix with "/me" unconditionally; change the
helper so it only uses "/me" when orgId is absent and when orgId is present it
sets and preserves the prefix to "/organizations/{orgId}" (do not overwrite it
later), update any conditional assignment/order so orgId wins, and add/adjust
unit tests to verify paths produce "/organizations/{orgId}/billing/..." when
orgId is provided.

)?.response as unknown as DeletedObjectJSON;
Expand Down
Loading