chore(backend): Add getOrganizationBillingSubscription to BillingApi

.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';
 

.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';
 

.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';
 

.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';
 

.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';
 

.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';
 

.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';
 

.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';