chore(backend): Add getOrganizationBillingSubscription to BillingApi (#6632)

Author: panteliselef

.changeset/fresh-clubs-float.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `getOrganizationBillingSubscription` to BillingApi.

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

@@ -229,6 +229,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "backend/commerce-subscription-item-webhook-event-json.mdx",
   "backend/commerce-subscription-item.mdx",
   "backend/commerce-subscription-webhook-event-json.mdx",
+  "backend/commerce-subscription.mdx",
   "backend/email-address.mdx",
   "backend/external-account.mdx",
   "backend/get-auth-fn.mdx",

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

@@ -2,11 +2,13 @@ import type { ClerkPaginationRequest } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
 import type { CommercePlan } from '../resources/CommercePlan';
+import type { CommerceSubscription } from '../resources/CommerceSubscription';
 import type { CommerceSubscriptionItem } from '../resources/CommerceSubscriptionItem';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/commerce';
+const organizationBasePath = '/organizations';
 
 type GetOrganizationListParams = ClerkPaginationRequest<{
   payerType: 'org' | 'user';
@@ -45,4 +47,16 @@ export class BillingAPI extends AbstractAPI {
       queryParams: params,
     });
   }
+
+  /**
+   * @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 getOrganizationBillingSubscription(organizationId: string) {
+    this.requireId(organizationId);
+    return this.request<CommerceSubscription>({
+      method: 'GET',
+      path: joinPaths(organizationBasePath, organizationId, 'billing', 'subscription'),
+    });
+  }
 }

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

@@ -0,0 +1,79 @@
+import { type CommerceMoneyAmount } from './CommercePlan';
+import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
+import type { CommerceSubscriptionJSON } from './JSON';
+
+/**
+ * @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 CommerceSubscription {
+  constructor(
+    /**
+     * The unique identifier for the commerce subscription.
+     */
+    readonly id: string,
+    /**
+     * The current status of the subscription.
+     */
+    readonly status: CommerceSubscriptionJSON['status'],
+    /**
+     * The ID of the payer for this subscription.
+     */
+    readonly payerId: string,
+    /**
+     * Unix timestamp (milliseconds) of creation.
+     */
+    readonly createdAt: number,
+    /**
+     * Unix timestamp (milliseconds) of last update.
+     */
+    readonly updatedAt: number,
+    /**
+     * Unix timestamp (milliseconds) when the subscription became active.
+     */
+    readonly activeAt: number | null,
+    /**
+     * Unix timestamp (milliseconds) when the subscription became past due.
+     */
+    readonly pastDueAt: number | null,
+    /**
+     * Array of subscription items in this subscription.
+     */
+    readonly subscriptionItems: CommerceSubscriptionItem[],
+    /**
+     * Information about the next scheduled payment.
+     */
+    readonly nextPayment: { date: number; amount: CommerceMoneyAmount } | null,
+    /**
+     * Whether the payer is eligible for a free trial.
+     */
+    readonly eligibleForFreeTrial: boolean,
+  ) {}
+
+  static fromJSON(data: CommerceSubscriptionJSON): CommerceSubscription {
+    const nextPayment = data.next_payment
+      ? {
+          date: data.next_payment.date,
+          amount: {
+            amount: data.next_payment.amount.amount,
+            amountFormatted: data.next_payment.amount.amount_formatted,
+            currency: data.next_payment.amount.currency,
+            currencySymbol: data.next_payment.amount.currency_symbol,
+          },
+        }
+      : null;
+
+    return new CommerceSubscription(
+      data.id,
+      data.status,
+      data.payer_id,
+      data.created_at,
+      data.updated_at,
+      data.active_at ?? null,
+      data.past_due_at ?? null,
+      data.subscription_items.map(item => CommerceSubscriptionItem.fromJSON(item)),
+      nextPayment,
+      data.eligible_for_free_trial ?? false,
+    );
+  }
+}

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

@@ -44,28 +44,45 @@ export class CommerceSubscriptionItem {
      * The plan ID.
      */
     readonly planId: string,
+    /**
+     * The date and time the subscription item was created.
+     */
+    readonly createdAt: number,
+    /**
+     * The date and time the subscription item was last updated.
+     */
+    readonly updatedAt: number,
     /**
      * The end of the current period.
      */
-    readonly periodEnd?: number,
+    readonly periodEnd: number | null,
     /**
      * When the subscription item was canceled.
      */
-    readonly canceledAt?: number,
+    readonly canceledAt: number | null,
     /**
      * When the subscription item became past due.
      */
-    readonly pastDueAt?: number,
+    readonly pastDueAt: number | null,
+    /**
+     * When the subscription item ended.
+     */
+    readonly endedAt: number | null,
+    /**
+     * The payer ID.
+     */
+    readonly payerId: string,
+    /**
+     * Whether this subscription item is currently in a free trial period.
+     */
+    readonly isFreeTrial?: boolean,
     /**
      * The lifetime amount paid for this subscription item.
      */
     readonly lifetimePaid?: CommerceMoneyAmount | null,
   ) {}
 
   static fromJSON(data: CommerceSubscriptionItemJSON): CommerceSubscriptionItem {
-    function formatAmountJSON(
-      amount: CommerceMoneyAmountJSON | null | undefined,
-    ): CommerceMoneyAmount | null | undefined;
     function formatAmountJSON(
       amount: CommerceMoneyAmountJSON | null | undefined,
     ): CommerceMoneyAmount | null | undefined {
@@ -90,9 +107,14 @@ export class CommerceSubscriptionItem {
       formatAmountJSON(data.amount),
       CommercePlan.fromJSON(data.plan),
       data.plan_id,
+      data.created_at,
+      data.updated_at,
       data.period_end,
       data.canceled_at,
       data.past_due_at,
+      data.ended_at,
+      data.payer_id,
+      data.is_free_trial,
       formatAmountJSON(data.lifetime_paid),
     );
   }

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

@@ -38,6 +38,7 @@ import {
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
 import { CommercePlan } from './CommercePlan';
+import { CommerceSubscription } from './CommerceSubscription';
 import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
@@ -184,6 +185,8 @@ function jsonToObject(item: any): any {
       return WaitlistEntry.fromJSON(item);
     case ObjectType.CommercePlan:
       return CommercePlan.fromJSON(item);
+    case ObjectType.CommerceSubscription:
+      return CommerceSubscription.fromJSON(item);
     case ObjectType.CommerceSubscriptionItem:
       return CommerceSubscriptionItem.fromJSON(item);
     case ObjectType.Feature:

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

@@ -861,10 +861,15 @@ export interface CommerceSubscriptionItemJSON extends ClerkResourceJSON {
   object: typeof ObjectType.CommerceSubscriptionItem;
   status: CommerceSubscriptionItemStatus;
   plan_period: 'month' | 'annual';
+  payer_id: string;
   period_start: number;
-  period_end?: number;
-  canceled_at?: number;
-  past_due_at?: number;
+  period_end: number | null;
+  is_free_trial?: boolean;
+  ended_at: number | null;
+  created_at: number;
+  updated_at: number;
+  canceled_at: number | null;
+  past_due_at: number | null;
   lifetime_paid: CommerceMoneyAmountJSON;
   next_payment: {
     amount: number;
@@ -972,6 +977,22 @@ export interface CommerceSubscriptionWebhookEventJSON extends ClerkResourceJSON
   items: CommerceSubscriptionItemWebhookEventJSON[];
 }
 
+export interface CommerceSubscriptionJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.CommerceSubscription;
+  status: 'active' | 'past_due' | 'canceled' | 'ended' | 'abandoned' | 'incomplete';
+  payer_id: string;
+  created_at: number;
+  updated_at: number;
+  active_at: number | null;
+  past_due_at: number | null;
+  subscription_items: CommerceSubscriptionItemJSON[];
+  next_payment?: {
+    date: number;
+    amount: CommerceMoneyAmountJSON;
+  };
+  eligible_for_free_trial?: boolean;
+}
+
 export interface WebhooksSvixJSON {
   svix_url: string;
 }

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

@@ -58,6 +58,7 @@ export * from './Verification';
 export * from './WaitlistEntry';
 export * from './Web3Wallet';
 export * from './CommercePlan';
+export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
 
 export type {

packages/backend/src/index.ts

@@ -101,6 +101,7 @@ export type {
   TestingTokenJSON,
   WebhooksSvixJSON,
   CommercePlanJSON,
+  CommerceSubscriptionJSON,
   CommerceSubscriptionItemJSON,
 } from './api/resources/JSON';
 
@@ -144,6 +145,7 @@ export type {
   User,
   TestingToken,
   CommercePlan,
+  CommerceSubscription,
   CommerceSubscriptionItem,
 } from './api/resources';