feat(backend): Add billing api and an endpoint for fetching plans

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**

.changeset/early-bats-shout.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add billing API for fetching available plans.

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

@@ -221,6 +221,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
  "backend/auth-object.mdx",
  "backend/authenticate-request-options.mdx",
  "backend/client.mdx",
+ "backend/commerce-plan-json.mdx",
+ "backend/commerce-plan.mdx",
  "backend/email-address.mdx",
  "backend/external-account.mdx",
  "backend/get-auth-fn.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -0,0 +1,26 @@
+import type { ClerkPaginationRequest } from '@clerk/types';
+
+import { joinPaths } from '../../util/path';
+import type { CommercePlan } from '../resources/CommercePlan';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/commerce';
+
+type GetOrganizationListParams = ClerkPaginationRequest<{
+ payerType: 'org' | 'user';
+}>;
+
+export class BillingAPI extends AbstractAPI {
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ public async getPlanList(params?: GetOrganizationListParams) {
+ return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+ method: 'GET',
+ path: joinPaths(basePath, 'plans'),
+ queryParams: params,
+ });
+ }
+}

packages/backend/src/api/factory.ts

@@ -29,6 +29,7 @@ import {
  WaitlistEntryAPI,
  WebhookAPI,
 } from './endpoints';
+import { BillingAPI } from './endpoints/BillingApi';
 import { buildRequest } from './request';
 
 export type CreateBackendApiOptions = Parameters<typeof buildRequest>[0];
@@ -52,6 +53,11 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
  ),
  betaFeatures: new BetaFeaturesAPI(request),
  blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+ /**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+ billing: new BillingAPI(request),
  clients: new ClientAPI(request),
  domains: new DomainAPI(request),
  emailAddresses: new EmailAddressAPI(request),

packages/backend/src/api/resources/CommercePlan.ts

@@ -0,0 +1,101 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+type CommerceFee = {
+ amount: number;
+ amountFormatted: string;
+ currency: string;
+ currencySymbol: string;
+};
+
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export class CommercePlan {
+ constructor(
+ /**
+ * The unique identifier for the plan.
+ */
+ readonly id: string,
+ /**
+ * The id of the product the plan belongs to.
+ */
+ readonly productId: string,
+ /**
+ * The name of the plan.
+ */
+ readonly name: string,
+ /**
+ * The URL-friendly identifier of the plan.
+ */
+ readonly slug: string,
+ /**
+ * The description of the plan.
+ */
+ readonly description: string | undefined,
+ /**
+ * Whether the plan is the default plan.
+ */
+ readonly isDefault: boolean,
+ /**
+ * Whether the plan is recurring.
+ */
+ readonly isRecurring: boolean,
+ /**
+ * Whether the plan has a base fee.
+ */
+ readonly hasBaseFee: boolean,
+ /**
+ * Whether the plan is displayed in the `<PriceTable/>` component.
+ */
+ readonly publiclyVisible: boolean,
+ /**
+ * The monthly fee of the plan.
+ */
+ readonly fee: CommerceFee,
+ /**
+ * The annual fee of the plan.
+ */
+ readonly annualFee: CommerceFee,
+ /**
+ * The annual fee of the plan on a monthly basis.
+ */
+ readonly annualMonthlyFee: CommerceFee,
+ /**
+ * The type of payer for the plan.
+ */
+ readonly forPayerType: 'org' | 'user',
+ /**
+ * The features the plan offers.
+ */
+ readonly features: Feature[],
+ ) {}
+
+ static fromJSON(data: CommercePlanJSON): CommercePlan {
+ const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+ return {
+ amount: fee.amount,
+ amountFormatted: fee.amount_formatted,
+ currency: fee.currency,
+ currencySymbol: fee.currency_symbol,
+ };
+ };
+ return new CommercePlan(
+ data.id,
+ data.product_id,
+ data.name,
+ data.slug,
+ data.description,
+ data.is_default,
+ data.is_recurring,
+ data.has_base_fee,
+ data.publicly_visible,
+ formatAmountJSON(data.fee),
+ formatAmountJSON(data.annual_fee),
+ formatAmountJSON(data.annual_monthly_fee),
+ data.for_payer_type,
+ data.features.map(feature => Feature.fromJSON(feature)),
+ );
+ }
+}

packages/backend/src/api/resources/Deserializer.ts

@@ -37,6 +37,8 @@ import {
  User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
+import { CommercePlan } from './CommercePlan';
+import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
@@ -179,6 +181,10 @@ function jsonToObject(item: any): any {
  return User.fromJSON(item);
  case ObjectType.WaitlistEntry:
  return WaitlistEntry.fromJSON(item);
+ case ObjectType.CommercePlan:
+ return CommercePlan.fromJSON(item);
+ case ObjectType.Feature:
+ return Feature.fromJSON(item);
  default:
  return item;
  }

packages/backend/src/api/resources/Feature.ts

@@ -0,0 +1,15 @@
+import type { FeatureJSON } from './JSON';
+
+export class Feature {
+ constructor(
+ readonly id: string,
+ readonly name: string,
+ readonly description: string,
+ readonly slug: string,
+ readonly avatarUrl: string,
+ ) {}
+
+ static fromJSON(data: FeatureJSON): Feature {
+ return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url);
+ }
+}

packages/backend/src/api/resources/JSON.ts

@@ -69,6 +69,8 @@ export const ObjectType = {
  CommercePaymentAttempt: 'commerce_payment_attempt',
  CommerceSubscription: 'commerce_subscription',
  CommerceSubscriptionItem: 'commerce_subscription_item',
+ CommercePlan: 'commerce_plan',
+ Feature: 'feature',
 } as const;
 
 export type ObjectType = (typeof ObjectType)[keyof typeof ObjectType];
@@ -791,71 +793,65 @@ export interface CommercePayerJSON extends ClerkResourceJSON {
  updated_at: number;
 }
 
-export interface CommercePayeeJSON {
+interface CommercePayeeJSON {
  id: string;
  gateway_type: string;
  gateway_external_id: string;
  gateway_status: 'active' | 'pending' | 'restricted' | 'disconnected';
 }
 
-export interface CommerceAmountJSON {
+interface CommerceFeeJSON {
  amount: number;
  amount_formatted: string;
  currency: string;
  currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
- subtotal: CommerceAmountJSON;
- tax_total: CommerceAmountJSON;
- grand_total: CommerceAmountJSON;
+interface CommerceTotalsJSON {
+ subtotal: CommerceFeeJSON;
+ tax_total: CommerceFeeJSON;
+ grand_total: CommerceFeeJSON;
 }
 
-export interface CommercePaymentSourceJSON {
- id: string;
- gateway: string;
- gateway_external_id: string;
- gateway_external_account_id?: string;
- payment_method: string;
- status: 'active' | 'disconnected';
- card_type?: string;
- last4?: string;
-}
-
-export interface CommercePaymentFailedReasonJSON {
- code: string;
- decline_code: string;
-}
-
-export interface CommerceSubscriptionCreditJSON {
- amount: CommerceAmountJSON;
- cycle_days_remaining: number;
- cycle_days_total: number;
- cycle_remaining_percent: number;
+export interface FeatureJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.Feature;
+ name: string;
+ description: string;
+ slug: string;
+ avatar_url: string;
 }
 
-export interface CommercePlanJSON {
+/**
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
+ * It is advised to pin the SDK version to avoid breaking changes.
+ */
+export interface CommercePlanJSON extends ClerkResourceJSON {
+ object: typeof ObjectType.CommercePlan;
  id: string;
- instance_id: string;
  product_id: string;
  name: string;
  slug: string;
  description?: string;
  is_default: boolean;
  is_recurring: boolean;
- amount: number;
- period: 'month' | 'annual';
- interval: number;
  has_base_fee: boolean;
- currency: string;
- annual_monthly_amount: number;
  publicly_visible: boolean;
+ fee: CommerceFeeJSON;
+ annual_fee: CommerceFeeJSON;
+ annual_monthly_fee: CommerceFeeJSON;
+ for_payer_type: 'org' | 'user';
+ features: FeatureJSON[];
 }
 
 export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  object: typeof ObjectType.CommerceSubscriptionItem;
  status: 'abandoned' | 'active' | 'canceled' | 'ended' | 'expired' | 'incomplete' | 'past_due' | 'upcoming';
- credit: CommerceSubscriptionCreditJSON;
+ credit: {
+ amount: CommerceFeeJSON;
+ cycle_days_remaining: number;
+ cycle_days_total: number;
+ cycle_remaining_percent: number;
+ };
  proration_date: string;
  plan_period: 'month' | 'annual';
  period_start: number;
@@ -865,8 +861,24 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
  lifetime_paid: number;
  next_payment_amount: number;
  next_payment_date: number;
- amount: CommerceAmountJSON;
- plan: CommercePlanJSON;
+ amount: CommerceFeeJSON;
+ plan: {
+ id: string;
+ instance_id: string;
+ product_id: string;
+ name: string;
+ slug: string;
+ description?: string;
+ is_default: boolean;
+ is_recurring: boolean;
+ amount: number;
+ period: 'month' | 'annual';
+ interval: number;
+ has_base_fee: boolean;
+ currency: string;
+ annual_monthly_amount: number;
+ publicly_visible: boolean;
+ };
  plan_id: string;
 }
 
@@ -881,13 +893,25 @@ export interface CommercePaymentAttemptJSON extends ClerkResourceJSON {
  updated_at: number;
  paid_at?: number;
  failed_at?: number;
- failed_reason?: CommercePaymentFailedReasonJSON;
+ failed_reason?: {
+ code: string;
+ decline_code: string;
+ };
  billing_date: number;
  charge_type: 'checkout' | 'recurring';
  payee: CommercePayeeJSON;
  payer: CommercePayerJSON;
  totals: CommerceTotalsJSON;
- payment_source: CommercePaymentSourceJSON;
+ payment_source: {
+ id: string;
+ gateway: string;
+ gateway_external_id: string;
+ gateway_external_account_id?: string;
+ payment_method: string;
+ status: 'active' | 'disconnected';
+ card_type?: string;
+ last4?: string;
+ };
  subscription_items: CommerceSubscriptionItemJSON[];
 }
 

packages/backend/src/api/resources/index.ts

@@ -57,6 +57,7 @@ export * from './User';
 export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
+export * from './CommercePlan';
 
 export type {
  EmailWebhookEvent,

packages/backend/src/index.ts

@@ -101,12 +101,6 @@ export type {
  TestingTokenJSON,
  WebhooksSvixJSON,
  CommercePayerJSON,
- CommercePayeeJSON,
- CommerceAmountJSON,
- CommerceTotalsJSON,
- CommercePaymentSourceJSON,
- CommercePaymentFailedReasonJSON,
- CommerceSubscriptionCreditJSON,
  CommercePlanJSON,
  CommerceSubscriptionItemJSON,
  CommercePaymentAttemptJSON,
@@ -150,6 +144,7 @@ export type {
  Token,
  User,
  TestingToken,
+ CommercePlan,
 } from './api/resources';
 
 /**