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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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
1 commit
Select commit
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
31 changes: 19 additions & 12 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,11 +28,22 @@ import {
} from '../../resources/internal';

export class Billing implements BillingNamespace {
static readonly #pathRoot = '/billing';
static path(subPath: string, param?: { orgId?: string }): string {
const { orgId } = param || {};
let prefix = '';
if (orgId) {
prefix = `/organizations/${orgId}`;
}
prefix = '/me';
return `${prefix}${Billing.#pathRoot}${subPath}`;
}
Comment on lines +31 to +40
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

Org-specific billing routes are now broken.

Billing.path always resets the prefix to /me, so every caller—including those that pass orgId—now hits /me/billing/.... This regresses all organization-scoped billing operations (statements, payment sources, subscription items, checkout confirmation, etc.), which will 404 or operate on the wrong tenant. Please restore the conditional prefix so that orgId-backed requests keep using /organizations/{orgId}/billing/....

-    let prefix = '';
-    if (orgId) {
-      prefix = `/organizations/${orgId}`;
-    }
-    prefix = '/me';
-    return `${prefix}${Billing.#pathRoot}${subPath}`;
+    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
static readonly #pathRoot = '/billing';
static path(subPath: string, param?: { orgId?: string }): string {
const { orgId } = param || {};
let prefix = '';
if (orgId) {
prefix = `/organizations/${orgId}`;
}
prefix = '/me';
return `${prefix}${Billing.#pathRoot}${subPath}`;
}
static readonly #pathRoot = '/billing';
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/modules/billing/namespace.ts around lines 31 to
40, the prefix is unconditionally reset to '/me' which ignores orgId and breaks
organization-scoped billing routes; restore the conditional so when param.orgId
is provided the prefix remains `/organizations/${orgId}` and only use '/me' when
no orgId is present, then return `${prefix}${Billing.#pathRoot}${subPath}` as
before; ensure no other code overrides prefix after the orgId check.


getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
const { for: forParam, ...safeParams } = params || {};
const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };
return await BaseResource._fetch({
path: `/commerce/plans`,
path: Billing.path('/plans'),
method: 'GET',
search: convertPageToOffsetSearchParams(searchParams),
}).then(res => {
Expand All @@ -48,15 +59,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.path(`/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 @@ -65,7 +76,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 @@ -82,9 +93,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 @@ -97,7 +106,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 @@ -112,9 +121,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 @@ -124,7 +131,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
9 changes: 4 additions & 5 deletions packages/clerk-js/src/core/modules/billing/payment-source-methods.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,13 @@ import type {

import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
import { Billing } from './namespace';

export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
const { orgId, ...rest } = params;
const json = (
await BaseResource._fetch({
path: orgId
? `/organizations/${orgId}/commerce/payment_sources/initialize`
: `/me/commerce/payment_sources/initialize`,
path: Billing.path(`/payment_sources/initialize`, { orgId }),
method: 'POST',
body: rest as any,
})
Expand All @@ -29,7 +28,7 @@ export const addPaymentSource = async (params: AddPaymentSourceParams) => {

const json = (
await BaseResource._fetch({
path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
path: Billing.path(`/payment_sources`, { orgId }),
method: 'POST',
body: rest as any,
})
Expand All @@ -41,7 +40,7 @@ export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
const { orgId, ...rest } = params;

return await BaseResource._fetch({
path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
path: Billing.path(`/payment_sources`, { orgId }),
method: 'GET',
search: convertPageToOffsetSearchParams(rest),
}).then(res => {
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 @@ -11,6 +11,7 @@ import type {
import { unixEpochToDate } from '@/utils/date';

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

Expand Down Expand Up @@ -60,9 +61,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,
}),
Comment on lines +64 to 66
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

Confirm checkout fails for organization payers

Line 64 relies on Billing.path, which currently ignores orgId and always returns the /me/billing/... path. As a result, confirming an organization checkout will call the wrong endpoint. Please fix Billing.path to respect the organization prefix before merging.

🤖 Prompt for AI Agents 
In packages/clerk-js/src/core/resources/BillingCheckout.ts around lines 64 to
66, the call to Billing.path(..., { orgId: this.payer.organizationId }) fails
because Billing.path currently ignores orgId and always returns a
/me/billing/... path; update Billing.path to prepend the organization prefix
when an orgId is provided (i.e., return /organizations/{orgId}/billing/...
instead of /me/billing/...), keep the existing behavior when orgId is undefined,
and ensure the path builder is used consistently by other callers (adjust or add
tests to cover both org and me paths).

{
Expand Down
9 changes: 3 additions & 6 deletions packages/clerk-js/src/core/resources/BillingPaymentSource.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import type {
RemovePaymentSourceParams,
} from '@clerk/types';

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

export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
Expand Down Expand Up @@ -47,9 +48,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
const { orgId } = params ?? {};
const json = (
await BaseResource._fetch({
path: orgId
? `/organizations/${orgId}/commerce/payment_sources/${this.id}`
: `/me/commerce/payment_sources/${this.id}`,
path: Billing.path(`/payment_sources/${this.id}`, { orgId }),
method: 'DELETE',
})
)?.response as unknown as DeletedObjectJSON;
Expand All @@ -60,9 +59,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
const { orgId } = params ?? {};
await BaseResource._fetch({
path: orgId
? `/organizations/${orgId}/commerce/payers/default_payment_source`
: `/me/commerce/payers/default_payment_source`,
path: Billing.path(`/payers/default_payment_source`, { orgId }),
method: 'PUT',
body: { payment_source_id: this.id } 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