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

clerk · panteliselef · Aug 8, 2025 · Jul 31, 2025 · Jul 31, 2025 · Jul 31, 2025
commit e853b50bd6a49fa8ef1fdaba451e3b2d88f957b8
diff --git a/.changeset/early-bats-shout.md b/.changeset/early-bats-shout.md
@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+WIP
diff --git a/packages/backend/src/api/endpoints/BillingApi.ts b/packages/backend/src/api/endpoints/BillingApi.ts
@@ -0,0 +1,20 @@
+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<unknown>;
+
+export class BillingAPI extends AbstractAPI {
+  public async getPlanList(params?: GetOrganizationListParams) {
+    return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+      method: 'GET',
+      path: joinPaths(basePath, 'plans'),
+      queryParams: params,
+    });
+  }
+}
diff --git a/packages/backend/src/api/factory.ts b/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,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     ),
     betaFeatures: new BetaFeaturesAPI(request),
     blocklistIdentifiers: new BlocklistIdentifierAPI(request),
+    billing: new BillingAPI(request),
     clients: new ClientAPI(request),
     domains: new DomainAPI(request),
     emailAddresses: new EmailAddressAPI(request),

diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
@@ -0,0 +1,112 @@
+import { Feature } from './Feature';
+import type { CommercePlanJSON } from './JSON';
+
+/**
+ * The Backend `Organization` object is similar to the [`Organization`](https://clerk.com/docs/references/javascript/organization) object as it holds information about an organization, as well as methods for managing it. However, the Backend `Organization` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Organizations#operation/ListOrganizations){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ */
+
+type CommerceAmount = {
+  amount: number;
+  amountFormatted: string;
+  currency: string;
+  currencySymbol: string;
+};
+
+export class CommercePlan {
+  constructor(
+    /**
+     * The unique identifier for the organization.
+     */
+    readonly id: string,
+    /**
+     * The name of the organization.
+     */
+    readonly productId: string,
+    /**
+     * The URL-friendly identifier of the user's active organization. If supplied, it must be unique for the instance.
+     */
+    readonly name: string,
+    /**
+     * Holds the organization's logo. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/image-optimization).
+     */
+    readonly slug: string,
+    /**
+     * Whether the organization has an image.
+     */
+    readonly description: string | undefined,
+    /**
+     * The date when the organization was first created.
+     */
+    readonly isDefault: boolean,
+    /**
+     * The date when the organization was last updated.
+     */
+    readonly isRecurring: boolean,
+    /**
+     * Metadata that can be read from the Frontend API and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} and can be set only from the Backend API.
+     */
+    readonly amount: number,
+    /**
+     * Metadata that can be read and set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}.
+     */
+    readonly period: 'month' | 'annual',
+    /**
+     * The maximum number of memberships allowed in the organization.
+     */
+    readonly interval: number,
+    /**
+     * Whether the organization allows admins to delete users.
+     */
+    readonly hasBaseFee: boolean,
+    /**
+     * The number of members in the organization.
+     */
+    readonly currency: string,
+    /**
+     * The ID of the user who created the organization.
+     */
+    readonly annualMonthlyAmount: number,
+    /**
+     * Whether the organization allows admins to delete users.
+     */
+    readonly publiclyVisible: boolean,
+    readonly fee: CommerceAmount,
+    readonly annualFee: CommerceAmount,
+    readonly annualMonthlyFee: CommerceAmount,
+    readonly forPayerType: 'org' | 'user',
+    readonly features: Feature[],
+  ) {}
+
+  static fromJSON(data: CommercePlanJSON): CommercePlan {
+    console.log('data', data);
+    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.amount,
+      data.period,
+      data.interval,
+      data.has_base_fee,
+      data.currency,
+      data.annual_monthly_amount,
+      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)),
+    );
+  }
+}
diff --git a/packages/backend/src/api/resources/Deserializer.ts b/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;
   }

diff --git a/packages/backend/src/api/resources/Feature.ts b/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);
+  }
+}
diff --git a/packages/backend/src/api/resources/JSON.ts b/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];
@@ -792,52 +794,37 @@ 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 CommerceAmountJSON {
   amount: number;
   amount_formatted: string;
   currency: string;
   currency_symbol: string;
 }
 
-export interface CommerceTotalsJSON {
+interface CommerceTotalsJSON {
   subtotal: CommerceAmountJSON;
   tax_total: CommerceAmountJSON;
   grand_total: CommerceAmountJSON;
 }
 
-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 {
+export interface CommercePlanJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.CommercePlan;
   id: string;
-  instance_id: string;
   product_id: string;
   name: string;
   slug: string;
@@ -846,17 +833,28 @@ export interface CommercePlanJSON {
   is_recurring: boolean;
   amount: number;
   period: 'month' | 'annual';
+  // What is this ?
   interval: number;
   has_base_fee: boolean;
   currency: string;
   annual_monthly_amount: number;
   publicly_visible: boolean;
+  fee: CommerceAmountJSON;
+  annual_fee: CommerceAmountJSON;
+  annual_monthly_fee: CommerceAmountJSON;
+  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: CommerceAmountJSON;
+    cycle_days_remaining: number;
+    cycle_days_total: number;
+    cycle_remaining_percent: number;
+  };
   proration_date: string;
   plan_period: 'month' | 'annual';
   period_start: number;
@@ -867,7 +865,23 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
   next_payment_amount: number;
   next_payment_date: number;
   amount: CommerceAmountJSON;
-  plan: CommercePlanJSON;
+  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;
 }
 
@@ -882,13 +896,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[];
 }
 

diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
@@ -101,12 +101,6 @@ export type {
   TestingTokenJSON,
   WebhooksSvixJSON,
   CommercePayerJSON,
-  CommercePayeeJSON,
-  CommerceAmountJSON,
-  CommerceTotalsJSON,
-  CommercePaymentSourceJSON,
-  CommercePaymentFailedReasonJSON,
-  CommerceSubscriptionCreditJSON,
   CommercePlanJSON,
   CommerceSubscriptionItemJSON,
   CommercePaymentAttemptJSON,