chore(clerk-js,types): Align payment methods terminology

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/act-claim.mdx",
  "types/act-jwt-claim.mdx",
  "types/active-session-resource.mdx",
- "types/add-payment-source-params.mdx",
+ "types/add-payment-method-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-initialized-payment-method-json.mdx",
+ "types/billing-initialized-payment-method-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-methods.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-method-json.mdx",
+ "types/billing-payment-method-resource.mdx",
+ "types/billing-payment-method-status.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",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/field-errors.mdx",
  "types/for-payer-type.mdx",
  "types/get-payment-attempts-params.mdx",
- "types/get-payment-sources-params.mdx",
+ "types/get-payment-methods-params.mdx",
  "types/get-plans-params.mdx",
  "types/get-statements-params.mdx",
  "types/get-subscription-params.mdx",
  "types/get-token.mdx",
  "types/id-selectors.mdx",
- "types/initialize-payment-source-params.mdx",
+ "types/initialize-payment-method-params.mdx",
  "types/internal_checkout-props.mdx",
  "types/internal_plan-details-props.mdx",
  "types/internal_subscription-details-props.mdx",
  "types/jwt-claims.mdx",
  "types/jwt-header.mdx",
  "types/legacy-redirect-props.mdx",
  "types/localization-resource.mdx",
- "types/make-default-payment-source-params.mdx",
+ "types/make-default-payment-method-params.mdx",
  "types/multi-domain-and-or-proxy.mdx",
  "types/organization-custom-role-key.mdx",
  "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "types/protect-props.mdx",
  "types/record-to-path.mdx",
  "types/redirect-options.mdx",
- "types/remove-payment-source-params.mdx",
+ "types/remove-payment-method-params.mdx",
  "types/reverification-config.mdx",
  "types/saml-strategy.mdx",
  "types/sdk-metadata.mdx",

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+ static readonly #pathRoot = '/commerce';
+ static path(subPath: string, param?: { orgId?: string }): string {
+ const { orgId } = param || {};
+ const prefix = orgId ? `/organizations/${orgId}` : '/me';
+ return `${prefix}${Billing.#pathRoot}${subPath}`;
+ }
+
  getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
  const { for: forParam, ...safeParams } = params || {};
  const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-AddPaymentSourceParams,
-BillingInitializedPaymentSourceJSON,
-BillingPaymentSourceJSON,
+AddPaymentMethodParams,
+BillingInitializedPaymentMethodJSON,
+BillingPaymentMethodJSON,
  ClerkPaginatedResponse,
-GetPaymentSourcesParams,
-InitializePaymentSourceParams,
+GetPaymentMethodsParams,
+InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
  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_METHODS_PATH}/initialize`, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingInitializedPaymentSourceJSON;
- return new BillingInitializedPaymentSource(json);
+ )?.response as unknown as BillingInitializedPaymentMethodJSON;
+ return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
  const { orgId, ...rest } = params;
 
  const json = (
  await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'POST',
  body: rest as any,
  })
- )?.response as unknown as BillingPaymentSourceJSON;
- return new BillingPaymentSource(json);
+ )?.response as unknown as BillingPaymentMethodJSON;
+ return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
  const { orgId, ...rest } = params;
 
  return await BaseResource._fetch({
- path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+ path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
  method: 'GET',
  search: convertPageToOffsetSearchParams(rest),
  }).then(res => {
  const { data: paymentSources, total_count } =
- res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+ res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
  return {
  total_count,
- data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+ data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
  };
  });
 };

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

@@ -5,6 +5,7 @@ import type {
  BillingCheckoutResource,
  BillingCheckoutTotals,
  BillingPayerResource,
+ BillingPaymentMethodResource,
  BillingSubscriptionPlanPeriod,
  ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
  id!: string;
  externalClientSecret!: string;
  externalGatewayId!: string;
-paymentSource?: BillingPaymentSource;
+paymentMethod?: BillingPaymentMethodResource;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
  this.id = data.id;
  this.externalClientSecret = data.external_client_secret;
  this.externalGatewayId = data.external_gateway_id;
- this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+ this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
  BillingMoneyAmount,
  BillingPaymentChargeType,
  BillingPaymentJSON,
+ BillingPaymentMethodResource,
  BillingPaymentResource,
- BillingPaymentSourceResource,
  BillingPaymentStatus,
  BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
  id!: string;
  amount!: BillingMoneyAmount;
  failedAt?: Date;
  paidAt?: Date;
  updatedAt!: Date;
-paymentSource!: BillingPaymentSourceResource;
+paymentMethod!: BillingPaymentMethodResource;
  subscriptionItem!: BillingSubscriptionItemResource;
  chargeType!: BillingPaymentChargeType;
  status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
  this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
  this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
  this.updatedAt = unixEpochToDate(data.updated_at);
- this.paymentSource = new BillingPaymentSource(data.payment_source);
+ this.paymentMethod = new BillingPaymentMethod(data.payment_method);
  this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
  this.chargeType = data.charge_type;
  this.status = data.status;

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

@@ -1,39 +1,39 @@
 import type {
-BillingInitializedPaymentSourceJSON,
-BillingInitializedPaymentSourceResource,
-BillingPaymentSourceJSON,
-BillingPaymentSourceResource,
-BillingPaymentSourceStatus,
+BillingInitializedPaymentMethodJSON,
+BillingInitializedPaymentMethodResource,
+BillingPaymentMethodJSON,
+BillingPaymentMethodResource,
+BillingPaymentMethodStatus,
  DeletedObjectJSON,
-MakeDefaultPaymentSourceParams,
-RemovePaymentSourceParams,
+MakeDefaultPaymentMethodParams,
+RemovePaymentMethodParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
  id!: string;
  last4!: string;
-paymentMethod!: string;
+paymentType!: 'card' | 'link';
  cardType!: string;
  isDefault!: boolean;
  isRemovable!: boolean;
- status!: BillingPaymentSourceStatus;
+ status!: BillingPaymentMethodStatus;
  walletType: string | undefined;
 
- constructor(data: BillingPaymentSourceJSON) {
+ constructor(data: BillingPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }
 
  this.id = data.id;
  this.last4 = data.last4;
- this.paymentMethod = data.payment_method;
+ this.paymentType = data.payment_type;
  this.cardType = data.card_type;
  this.isDefault = data.is_default;
  this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return this;
  }
 
- public async remove(params?: RemovePaymentSourceParams) {
+ public async remove(params?: RemovePaymentMethodParams) {
  const { orgId } = params ?? {};
  const json = (
  await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  return new DeletedObject(json);
  }
 
- public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+ public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
  const { orgId } = params ?? {};
  await BaseResource._fetch({
  path: orgId
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
  }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
  externalClientSecret!: string;
  externalGatewayId!: string;
  paymentMethodOrder!: string[];
 
- constructor(data: BillingInitializedPaymentSourceJSON) {
+ constructor(data: BillingInitializedPaymentMethodJSON) {
  super();
  this.fromJSON(data);
  }
 
- protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+ protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
  if (!data) {
  return this;
  }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
  id!: string;
-paymentSourceId!: string;
+paymentMethodId!: string;
  plan!: BillingPlan;
  planPeriod!: BillingSubscriptionPlanPeriod;
  status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
  }
 
  this.id = data.id;
- this.paymentSourceId = data.payment_source_id;
+ this.paymentMethodId = data.payment_method_id;
  this.plan = new BillingPlan(data.plan);
  this.planPeriod = data.plan_period;
  this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
  }).then(res => new Organization(res?.response as OrganizationJSON));
  };
 
-initializePaymentSource: typeof initializePaymentSource = params => {
- return initializePaymentSource({
+initializePaymentMethod: typeof initializePaymentMethod = params => {
+ return initializePaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-addPaymentSource: typeof addPaymentSource = params => {
- return addPaymentSource({
+addPaymentMethod: typeof addPaymentMethod = params => {
+ return addPaymentMethod({
  ...params,
  orgId: this.id,
  });
  };
 
-getPaymentSources: typeof getPaymentSources = params => {
- return getPaymentSources({
+getPaymentMethods: typeof getPaymentMethods = params => {
+ return getPaymentMethods({
  ...params,
  orgId: this.id,
  });