From 767a1663cf5f8328893295e429fca39647af638d Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:09:50 -0400
Subject: [PATCH 01/13] chore(backend,types): Update JSDoc comments & export
 Feature type

---
 .changeset/three-knives-play.md               |   6 +
 .typedoc/custom-plugin.mjs                    |   1 +
 .../backend/src/api/resources/CommercePlan.ts |  21 +-
 .../src/api/resources/CommerceSubscription.ts |   7 +-
 .../api/resources/CommerceSubscriptionItem.ts |  23 +-
 packages/backend/src/api/resources/Feature.ts |  18 +
 packages/backend/src/api/resources/index.ts   |   1 +
 packages/backend/src/index.ts                 |   1 +
 packages/types/src/commerce.ts                | 377 ++++--------------
 9 files changed, 139 insertions(+), 316 deletions(-)
 create mode 100644 .changeset/three-knives-play.md

diff --git a/.changeset/three-knives-play.md b/.changeset/three-knives-play.md
new file mode 100644
index 00000000000..4e01d4f1da8
--- /dev/null
+++ b/.changeset/three-knives-play.md
@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/types': patch
+---
+
+export feature type from backend resource
diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs
index ee584a16964..904d1e4cf35 100644
--- a/.typedoc/custom-plugin.mjs
+++ b/.typedoc/custom-plugin.mjs
@@ -55,6 +55,7 @@ const LINK_REPLACEMENTS = [
   ['verify-token-options', '#verify-token-options'],
   ['localization-resource', '/docs/customization/localization'],
   ['commerce-subscription-item-resource', '/docs/references/javascript/types/commerce-subscription-item-resource'],
+  ['commerce-money-amount', '/docs/references/javascript/types/commerce-money-amount'],
 ];
 
 /**
diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
index 8cf2ffbc968..3e7d920f727 100644
--- a/packages/backend/src/api/resources/CommercePlan.ts
+++ b/packages/backend/src/api/resources/CommercePlan.ts
@@ -1,16 +1,31 @@
 import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
+/**
+ * The `CommerceMoneyAmount` type represents a monetary value with currency information.
+ * @type
+ */
 export type CommerceMoneyAmount = {
+  /**
+   * The raw amount as a number, usually in the smallest unit of the currency (like cents for USD). For example, `1000` for $10.00.
+   */
   amount: number;
+  /**
+   * The amount as a formatted string. For example, `10` for $10.00.
+   */
   amountFormatted: string;
+  /**
+   * The ISO currency code for this amount. For example, `USD` or `EUR`.
+   */
   currency: string;
+  /**
+   * The symbol for the currency. For example, `$`, `€`, or `£`.
+   */
   currencySymbol: string;
 };
 
 /**
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
- * It is advised to pin the SDK version to avoid breaking changes.
+ * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class CommercePlan {
   constructor(
@@ -19,7 +34,7 @@ export class CommercePlan {
      */
     readonly id: string,
     /**
-     * The id of the product the plan belongs to.
+     * The ID of the product the plan belongs to.
      */
     readonly productId: string,
     /**
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 8b80c155f35..89f2357e80c 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -3,8 +3,7 @@ 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.
+ * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class CommerceSubscription {
   constructor(
@@ -21,11 +20,11 @@ export class CommerceSubscription {
      */
     readonly payerId: string,
     /**
-     * Unix timestamp (milliseconds) of creation.
+     * Unix timestamp (milliseconds) when the subscription was created.
      */
     readonly createdAt: number,
     /**
-     * Unix timestamp (milliseconds) of last update.
+     * Unix timestamp (milliseconds) when the subscription was last updated.
      */
     readonly updatedAt: number,
     /**
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index 3e57cfa94ea..013dcdfac28 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -4,8 +4,7 @@ import { type CommerceMoneyAmount, CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } 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.
+ * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  */
 export class CommerceSubscriptionItem {
   constructor(
@@ -22,14 +21,20 @@ export class CommerceSubscriptionItem {
      */
     readonly planPeriod: 'month' | 'annual',
     /**
-     * The start of the current period.
+     * Unix timestamp (milliseconds) when the current period starts.
      */
     readonly periodStart: number,
     /**
      * The next payment information.
      */
     readonly nextPayment: {
+      /**
+       * The amount of the next payment.
+       */
       amount: number;
+      /**
+       * Unix timestamp (milliseconds) when the next payment is scheduled.
+       */
       date: number;
     } | null,
     /**
@@ -45,27 +50,27 @@ export class CommerceSubscriptionItem {
      */
     readonly planId: string,
     /**
-     * The date and time the subscription item was created.
+     * Unix timestamp (milliseconds) when the subscription item was created.
      */
     readonly createdAt: number,
     /**
-     * The date and time the subscription item was last updated.
+     * Unix timestamp (milliseconds) when the subscription item was last updated.
      */
     readonly updatedAt: number,
     /**
-     * The end of the current period.
+     * Unix timestamp (milliseconds) when the current period ends.
      */
     readonly periodEnd: number | null,
     /**
-     * When the subscription item was canceled.
+     * Unix timestamp (milliseconds) when the subscription item was canceled.
      */
     readonly canceledAt: number | null,
     /**
-     * When the subscription item became past due.
+     * Unix timestamp (milliseconds) when the subscription item became past due.
      */
     readonly pastDueAt: number | null,
     /**
-     * When the subscription item ended.
+     * Unix timestamp (milliseconds) when the subscription item ended.
      */
     readonly endedAt: number | null,
     /**
diff --git a/packages/backend/src/api/resources/Feature.ts b/packages/backend/src/api/resources/Feature.ts
index f1fa1d48774..5d75d8e7a3a 100644
--- a/packages/backend/src/api/resources/Feature.ts
+++ b/packages/backend/src/api/resources/Feature.ts
@@ -1,11 +1,29 @@
 import type { FeatureJSON } from './JSON';
 
+/**
+ * A feature of a subscription plan.
+ */
 export class Feature {
   constructor(
+    /**
+     * The unique identifier for the feature.
+     */
     readonly id: string,
+    /**
+     * The name of the feature.
+     */
     readonly name: string,
+    /**
+     * The description of the feature.
+     */
     readonly description: string,
+    /**
+     * The URL-friendly identifier of the feature.
+     */
     readonly slug: string,
+    /**
+     * The URL of the feature's avatar image.
+     */
     readonly avatarUrl: string,
   ) {}
 
diff --git a/packages/backend/src/api/resources/index.ts b/packages/backend/src/api/resources/index.ts
index f4be508678d..855fb43df45 100644
--- a/packages/backend/src/api/resources/index.ts
+++ b/packages/backend/src/api/resources/index.ts
@@ -60,6 +60,7 @@ export * from './Web3Wallet';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './Feature';
 
 export type {
   EmailWebhookEvent,
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
index 70a0f7fa064..5023e0e8df5 100644
--- a/packages/backend/src/index.ts
+++ b/packages/backend/src/index.ts
@@ -119,6 +119,7 @@ export type {
   Domain,
   EmailAddress,
   ExternalAccount,
+  Feature,
   Instance,
   InstanceRestrictions,
   InstanceSettings,
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 41cd93a193e..bc7fb3d09cd 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -4,6 +4,9 @@ import type { ClerkResource } from './resource';
 import type { CommerceFeatureJSONSnapshot } from './snapshots';
 
 type WithOptionalOrgType<T> = T & {
+  /**
+   * The organization ID to perform the request on.
+   */
   orgId?: string;
 };
 
@@ -141,12 +144,9 @@ export type ForPayerType = 'organization' | 'user';
 export type CommerceSubscriptionStatus = 'active' | 'ended' | 'upcoming' | 'past_due';
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The billing period for the plan.
+ *
+ * @inline
  */
 export type CommerceSubscriptionPlanPeriod = 'month' | 'annual';
 
@@ -413,61 +413,38 @@ export interface CommercePlanResource extends ClerkResource {
 }
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceFeatureResource` type represents a feature of a subscription plan.
  */
 export interface CommerceFeatureResource extends ClerkResource {
+  /**
+   * The unique identifier for the feature.
+   */
   id: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The display name of the feature.
    */
   name: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A short description of what the feature provides.
    */
   description: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A unique, URL-friendly identifier for the feature.
    */
   slug: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The URL of the feature's avatar image.
    */
   avatarUrl: string;
+  /**
+   * @hidden
+   */
   __internal_toSnapshot: () => CommerceFeatureJSONSnapshot;
 }
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The status of a payment source.
+ * @inline
  */
 export type CommercePaymentSourceStatus = 'active' | 'expired' | 'disconnected';
 
@@ -561,86 +538,53 @@ export type RemovePaymentSourceParams = WithOptionalOrgType<unknown>;
 export type MakeDefaultPaymentSourceParams = WithOptionalOrgType<unknown>;
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommercePaymentSourceResource` type represents a payment source for a checkout session.
  */
 export interface CommercePaymentSourceResource extends ClerkResource {
+  /**
+   * The unique identifier for the payment method.
+   */
   id: string;
+  /**
+   * The last four digits of the payment method.
+   */
   last4: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The type of payment method. For example, `'card'` or `'bank_account'`.
    */
   paymentMethod: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The brand or type of card. For example, `'visa'` or `'mastercard'`.
    */
   cardType: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Whether the payment method is set as the default for the account.
    */
   isDefault: boolean;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Whether the payment method can be removed by the user.
    */
   isRemovable: boolean;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The current status of the payment method.
    */
   status: CommercePaymentSourceStatus;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The type of digital wallet, if applicable. For example, `'apple_pay'`, or `'google_pay'`.
    */
   walletType: string | undefined;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A function that removes this payment source from the account. Accepts the following parameters:
+   * - `orgId?` (`string`): The ID of the organization to remove the payment source from.
+   * @param params - The parameters for the remove operation.
+   * @returns A promise that resolves to a `DeletedObjectResource` object.
    */
   remove: (params?: RemovePaymentSourceParams) => Promise<DeletedObjectResource>;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A function that sets this payment source as the default for the account. Accepts the following parameters:
+   * - `orgId?` (`string`): The ID of the organization to set as the default.
+   * @param params - The parameters for the make default operation.
+   * @returns A promise that resolves to `null`.
    */
   makeDefault: (params?: MakeDefaultPaymentSourceParams) => Promise<null>;
 }
@@ -877,30 +821,15 @@ export interface CommerceStatementResource extends ClerkResource {
 }
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceStatementGroup` type represents a group of payment items within a statement.
  */
 export interface CommerceStatementGroup {
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The date and time when this group of payment items was created or last updated.
    */
   timestamp: Date;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * An array of payment resources that belong to this group.
    */
   items: CommercePaymentResource[];
 }
@@ -1197,124 +1126,59 @@ export interface CommerceSubscriptionResource extends ClerkResource {
 }
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceMoneyAmount` type represents a monetary value with currency information.
  */
 export interface CommerceMoneyAmount {
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The raw amount as a number, usually in the smallest unit of the currency (like cents for USD). For example, `1000` for $10.00.
    */
   amount: number;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The amount as a formatted string. For example, `10` for $10.00.
    */
   amountFormatted: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The ISO currency code for this amount. For example, `USD` or `EUR`.
    */
   currency: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The symbol for the currency. For example, `$`, `€`, or `£`.
    */
   currencySymbol: string;
 }
 
 /**
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
- * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session.
  */
 export interface CommerceCheckoutTotals {
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The price of the items or plan before taxes, credits, or discounts are applied.
    */
   subtotal: CommerceMoneyAmount;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The total amount for the checkout, including taxes and after credits/discounts are applied. This is the final amount due.
    */
   grandTotal: CommerceMoneyAmount;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The amount of tax included in the checkout.
    */
   taxTotal: CommerceMoneyAmount;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The amount that needs to be immediately paid to complete the checkout.
    */
   totalDueNow: CommerceMoneyAmount;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Any credits (like account balance or promo credits) that are being applied to the checkout.
    */
   credit: CommerceMoneyAmount;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
    */
   pastDue: CommerceMoneyAmount;
 }
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceStatementTotals` type represents the total costs, taxes, and other pricing details for a statement.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface CommerceStatementTotals extends Omit<CommerceCheckoutTotals, 'totalDueNow'> {}
@@ -1349,174 +1213,87 @@ export type CreateCheckoutParams = WithOptionalOrgType<{
 }>;
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `confirm()` method accepts the following parameters. **Only one of `paymentSourceId`, `paymentToken`, or `useTestCard` should be provided.**
  */
 export type ConfirmCheckoutParams = WithOptionalOrgType<
   | {
       /**
-       * @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 and the clerk-js version to a specific version to avoid breaking changes.
-       * @example
-       * ```tsx
-       * <ClerkProvider clerkJsVersion="x.x.x" />
-       * ```
+       * The ID of a saved payment source to use for this checkout.
        */
       paymentSourceId?: string;
     }
   | {
       /**
-       * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-       * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-       * @example
-       * ```tsx
-       * <ClerkProvider clerkJsVersion="x.x.x" />
-       * ```
+       * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided.
        */
       paymentToken?: string;
       /**
-       * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-       * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-       * @example
-       * ```tsx
-       * <ClerkProvider clerkJsVersion="x.x.x" />
-       * ```
+       * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided.
        */
       gateway?: PaymentGateway;
     }
   | {
       /**
-       * @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 and the clerk-js version to a specific version to avoid breaking changes.
-       * @example
-       * ```tsx
-       * <ClerkProvider clerkJsVersion="x.x.x" />
-       * ```
+       * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided.
        */
       gateway?: PaymentGateway;
       /**
-       * @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 and the clerk-js version to a specific version to avoid breaking changes.
-       * @example
-       * ```tsx
-       * <ClerkProvider clerkJsVersion="x.x.x" />
-       * ```
+       * If true, uses a test card for the checkout. **Requires** `gateway` to be provided.
        */
       useTestCard?: boolean;
     }
 >;
 
 /**
- * @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 and the clerk-js version to a specific version to avoid breaking changes.
- * @example
- * ```tsx
- * <ClerkProvider clerkJsVersion="x.x.x" />
- * ```
+ * The `CommerceCheckoutResource` type represents information about a checkout session.
  */
 export interface CommerceCheckoutResource extends ClerkResource {
+  /**
+   * The unique identifier for the checkout session.
+   */
   id: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A client secret from an external payment provider (such as Stripe) used to complete the payment on the client-side.
    */
   externalClientSecret: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The identifier for the external payment gateway used for this checkout session.
    */
   externalGatewayId: string;
   /**
-   * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
-   * It is advised to pin the SDK version and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The payment source being used for the checkout, such as a credit card or bank account.
    */
   paymentSource?: CommercePaymentSourceResource;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The subscription plan details for the checkout.
    */
   plan: CommercePlanResource;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The billing period for the plan.
    */
   planPeriod: CommerceSubscriptionPlanPeriod;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Unix timestamp (milliseconds) when the current period starts.
    */
   planPeriodStart?: number;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The current status of the checkout session.
    */
   status: 'needs_confirmation' | 'completed';
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * The total costs, taxes, and other pricing details for the checkout.
    */
   totals: CommerceCheckoutTotals;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
    */
   confirm: (params: ConfirmCheckoutParams) => Promise<CommerceCheckoutResource>;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Whether the plan change will take effect immediately after checkout.
    */
   isImmediatePlanChange: boolean;
   /**
-   * @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 and the clerk-js version to a specific version to avoid breaking changes.
-   * @example
-   * ```tsx
-   * <ClerkProvider clerkJsVersion="x.x.x" />
-   * ```
+   * Unix timestamp (milliseconds) when the free trial ends.
    */
   freeTrialEndsAt: Date | null;
 }

From 4c745fcd98b640b11ffe96a97063a05551ddc652 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:46:36 -0400
Subject: [PATCH 02/13] docs review suggestions

---
 .../backend/src/api/resources/CommercePlan.ts | 25 ++-----------------
 .../src/api/resources/CommerceSubscription.ts |  2 +-
 .../api/resources/CommerceSubscriptionItem.ts |  4 +--
 packages/types/src/commerce.ts                |  6 ++---
 4 files changed, 8 insertions(+), 29 deletions(-)

diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
index 3e7d920f727..016b3e9f26a 100644
--- a/packages/backend/src/api/resources/CommercePlan.ts
+++ b/packages/backend/src/api/resources/CommercePlan.ts
@@ -1,31 +1,10 @@
+import { CommerceMoneyAmount } from '@clerk/types';
 import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
-/**
- * The `CommerceMoneyAmount` type represents a monetary value with currency information.
- * @type
- */
-export type CommerceMoneyAmount = {
-  /**
-   * The raw amount as a number, usually in the smallest unit of the currency (like cents for USD). For example, `1000` for $10.00.
-   */
-  amount: number;
-  /**
-   * The amount as a formatted string. For example, `10` for $10.00.
-   */
-  amountFormatted: string;
-  /**
-   * The ISO currency code for this amount. For example, `USD` or `EUR`.
-   */
-  currency: string;
-  /**
-   * The symbol for the currency. For example, `$`, `€`, or `£`.
-   */
-  currencySymbol: string;
-};
-
 /**
  * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export class CommercePlan {
   constructor(
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 89f2357e80c..7fc08631fe0 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -1,4 +1,4 @@
-import { type CommerceMoneyAmount } from './CommercePlan';
+import { type CommerceMoneyAmount } from '@clerk/types';
 import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import type { CommerceSubscriptionJSON } from './JSON';
 
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index 013dcdfac28..8b6ef061620 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -1,6 +1,6 @@
-import type { CommerceMoneyAmountJSON } from '@clerk/types';
+import type { CommerceMoneyAmountJSON, CommerceMoneyAmount } from '@clerk/types';
 
-import { type CommerceMoneyAmount, CommercePlan } from './CommercePlan';
+import { CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index bc7fb3d09cd..21f45d484b7 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -1134,15 +1134,15 @@ export interface CommerceMoneyAmount {
    */
   amount: number;
   /**
-   * The amount as a formatted string. For example, `10` for $10.00.
+   * The amount as a formatted string. For example, `10.00` for $10.00.
    */
   amountFormatted: string;
   /**
-   * The ISO currency code for this amount. For example, `USD` or `EUR`.
+   * The ISO currency code for this amount. For example, `USD`.
    */
   currency: string;
   /**
-   * The symbol for the currency. For example, `$`, `€`, or `£`.
+   * The symbol for the currency. For example, `$`.
    */
   currencySymbol: string;
 }

From 4b284ee8f57c6babb2ca0a4c791cc97290043242 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:59:06 -0400
Subject: [PATCH 03/13] unix timestamp OF

---
 .../src/api/resources/CommerceSubscription.ts    |  8 ++++----
 .../api/resources/CommerceSubscriptionItem.ts    | 16 ++++++++--------
 packages/types/src/commerce.ts                   |  4 ++--
 3 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 7fc08631fe0..6e273bc8950 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -20,19 +20,19 @@ export class CommerceSubscription {
      */
     readonly payerId: string,
     /**
-     * Unix timestamp (milliseconds) when the subscription was created.
+     * Unix timestamp (milliseconds) of when the subscription was created.
      */
     readonly createdAt: number,
     /**
-     * Unix timestamp (milliseconds) when the subscription was last updated.
+     * Unix timestamp (milliseconds) of when the subscription was last updated.
      */
     readonly updatedAt: number,
     /**
-     * Unix timestamp (milliseconds) when the subscription became active.
+     * Unix timestamp (milliseconds) of when the subscription became active.
      */
     readonly activeAt: number | null,
     /**
-     * Unix timestamp (milliseconds) when the subscription became past due.
+     * Unix timestamp (milliseconds) of when the subscription became past due.
      */
     readonly pastDueAt: number | null,
     /**
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index 8b6ef061620..7506642df3e 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -21,7 +21,7 @@ export class CommerceSubscriptionItem {
      */
     readonly planPeriod: 'month' | 'annual',
     /**
-     * Unix timestamp (milliseconds) when the current period starts.
+     * Unix timestamp (milliseconds) of when the current period starts.
      */
     readonly periodStart: number,
     /**
@@ -33,7 +33,7 @@ export class CommerceSubscriptionItem {
        */
       amount: number;
       /**
-       * Unix timestamp (milliseconds) when the next payment is scheduled.
+       * Unix timestamp (milliseconds) of when the next payment is scheduled.
        */
       date: number;
     } | null,
@@ -50,27 +50,27 @@ export class CommerceSubscriptionItem {
      */
     readonly planId: string,
     /**
-     * Unix timestamp (milliseconds) when the subscription item was created.
+     * Unix timestamp (milliseconds) of when the subscription item was created.
      */
     readonly createdAt: number,
     /**
-     * Unix timestamp (milliseconds) when the subscription item was last updated.
+     * Unix timestamp (milliseconds) of when the subscription item was last updated.
      */
     readonly updatedAt: number,
     /**
-     * Unix timestamp (milliseconds) when the current period ends.
+     * Unix timestamp (milliseconds) of when the current period ends.
      */
     readonly periodEnd: number | null,
     /**
-     * Unix timestamp (milliseconds) when the subscription item was canceled.
+     * Unix timestamp (milliseconds) of when the subscription item was canceled.
      */
     readonly canceledAt: number | null,
     /**
-     * Unix timestamp (milliseconds) when the subscription item became past due.
+     * Unix timestamp (milliseconds) of when the subscription item became past due.
      */
     readonly pastDueAt: number | null,
     /**
-     * Unix timestamp (milliseconds) when the subscription item ended.
+     * Unix timestamp (milliseconds) of when the subscription item ended.
      */
     readonly endedAt: number | null,
     /**
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 21f45d484b7..c9f3a31e23d 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -1273,7 +1273,7 @@ export interface CommerceCheckoutResource extends ClerkResource {
    */
   planPeriod: CommerceSubscriptionPlanPeriod;
   /**
-   * Unix timestamp (milliseconds) when the current period starts.
+   * Unix timestamp (milliseconds) of when the current period starts.
    */
   planPeriodStart?: number;
   /**
@@ -1293,7 +1293,7 @@ export interface CommerceCheckoutResource extends ClerkResource {
    */
   isImmediatePlanChange: boolean;
   /**
-   * Unix timestamp (milliseconds) when the free trial ends.
+   * Unix timestamp (milliseconds) of when the free trial ends.
    */
   freeTrialEndsAt: Date | null;
 }

From 27a94f6166b7ad0cb3cfd932ed758bc01f0612bb Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 14:05:25 -0400
Subject: [PATCH 04/13] add back experimental tag

---
 .../backend/src/api/resources/CommerceSubscription.ts     | 1 +
 .../backend/src/api/resources/CommerceSubscriptionItem.ts | 1 +
 packages/types/src/commerce.ts                            | 8 ++++++++
 3 files changed, 10 insertions(+)

diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 6e273bc8950..2c19eac3665 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -4,6 +4,7 @@ import type { CommerceSubscriptionJSON } from './JSON';
 
 /**
  * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * @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(
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index 7506642df3e..a9dd0c56025 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -5,6 +5,7 @@ import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
  * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * @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 CommerceSubscriptionItem {
   constructor(
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index c9f3a31e23d..52a56b832aa 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -414,6 +414,8 @@ export interface CommercePlanResource extends ClerkResource {
 
 /**
  * The `CommerceFeatureResource` type represents a feature of a subscription plan.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommerceFeatureResource extends ClerkResource {
   /**
@@ -539,6 +541,8 @@ export type MakeDefaultPaymentSourceParams = WithOptionalOrgType<unknown>;
 
 /**
  * The `CommercePaymentSourceResource` type represents a payment source for a checkout session.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommercePaymentSourceResource extends ClerkResource {
   /**
@@ -1149,6 +1153,8 @@ export interface CommerceMoneyAmount {
 
 /**
  * The `CommerceCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommerceCheckoutTotals {
   /**
@@ -1246,6 +1252,8 @@ export type ConfirmCheckoutParams = WithOptionalOrgType<
 
 /**
  * The `CommerceCheckoutResource` type represents information about a checkout session.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommerceCheckoutResource extends ClerkResource {
   /**

From acc25696f9b85a59d2c28c342e5ffdae4004bdbd Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 14:07:25 -0400
Subject: [PATCH 05/13] update changeset

---
 .changeset/three-knives-play.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.changeset/three-knives-play.md b/.changeset/three-knives-play.md
index 4e01d4f1da8..81553f188d8 100644
--- a/.changeset/three-knives-play.md
+++ b/.changeset/three-knives-play.md
@@ -3,4 +3,5 @@
 '@clerk/types': patch
 ---
 
-export feature type from backend resource
+- Export `Feature` type from backend resource.
+- Re-export canonical `CommerceMoneyAmount` type from `@clerk/types`.

From c9f4326a4959ef5178cda43650d8529ceaf9876d Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 14:58:32 -0400
Subject: [PATCH 06/13] sort imports

---
 packages/backend/src/api/resources/CommercePlan.ts             | 3 ++-
 packages/backend/src/api/resources/CommerceSubscription.ts     | 1 +
 packages/backend/src/api/resources/CommerceSubscriptionItem.ts | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
index 016b3e9f26a..abd68ea64f5 100644
--- a/packages/backend/src/api/resources/CommercePlan.ts
+++ b/packages/backend/src/api/resources/CommercePlan.ts
@@ -1,4 +1,5 @@
-import { CommerceMoneyAmount } from '@clerk/types';
+import type { CommerceMoneyAmount } from '@clerk/types';
+
 import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 2c19eac3665..9017117e612 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -1,4 +1,5 @@
 import { type CommerceMoneyAmount } from '@clerk/types';
+
 import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import type { CommerceSubscriptionJSON } from './JSON';
 
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index a9dd0c56025..92000e7bae6 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -1,4 +1,4 @@
-import type { CommerceMoneyAmountJSON, CommerceMoneyAmount } from '@clerk/types';
+import type { CommerceMoneyAmount, CommerceMoneyAmountJSON } from '@clerk/types';
 
 import { CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } from './JSON';

From 8720ec5cc811eeb1b2d3793b87d245775ee52594 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Wed, 27 Aug 2025 15:03:28 -0400
Subject: [PATCH 07/13] add feature to snapshot

---
 .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap b/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
index 62b308658bd..a3c26d82383 100644
--- a/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
+++ b/.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
@@ -232,6 +232,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "backend/commerce-subscription.mdx",
   "backend/email-address.mdx",
   "backend/external-account.mdx",
+  "backend/feature.mdx",
   "backend/get-auth-fn.mdx",
   "backend/identification-link.mdx",
   "backend/infer-auth-object-from-token-array.mdx",

From 7800b1e3f673692a3cec40e8121a750a8e3d9fd2 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 28 Aug 2025 11:27:12 -0400
Subject: [PATCH 08/13] handle TODOs

---
 packages/backend/src/api/resources/CommercePlan.ts             | 2 +-
 packages/backend/src/api/resources/CommerceSubscription.ts     | 2 +-
 packages/backend/src/api/resources/CommerceSubscriptionItem.ts | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
index abd68ea64f5..8eec600daf4 100644
--- a/packages/backend/src/api/resources/CommercePlan.ts
+++ b/packages/backend/src/api/resources/CommercePlan.ts
@@ -4,7 +4,7 @@ import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
 /**
- * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export class CommercePlan {
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index 9017117e612..ae990060225 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -4,7 +4,7 @@ import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import type { CommerceSubscriptionJSON } from './JSON';
 
 /**
- * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  * @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 {
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index 92000e7bae6..a19fc2911ed 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -4,7 +4,7 @@ import { CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
- * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](TODO){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items){{ target: '_blank' }} and is not directly accessible from the Frontend API.
  * @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 CommerceSubscriptionItem {

From 7942f850de816e00c895efa79aa0192f328d61a3 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 28 Aug 2025 11:49:34 -0400
Subject: [PATCH 09/13] small comment update

---
 packages/backend/src/api/resources/Feature.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/backend/src/api/resources/Feature.ts b/packages/backend/src/api/resources/Feature.ts
index 5d75d8e7a3a..7d1afeb96e9 100644
--- a/packages/backend/src/api/resources/Feature.ts
+++ b/packages/backend/src/api/resources/Feature.ts
@@ -1,7 +1,7 @@
 import type { FeatureJSON } from './JSON';
 
 /**
- * A feature of a subscription plan.
+ * The `Feature` object represents a feature of a subscription plan.
  */
 export class Feature {
   constructor(

From f161bf16c114afbed28ca71a4b3c0bb46d0fa0d9 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 28 Aug 2025 11:54:03 -0400
Subject: [PATCH 10/13] add experimental tags

---
 packages/backend/src/api/resources/Feature.ts | 2 ++
 packages/types/src/commerce.ts                | 6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/packages/backend/src/api/resources/Feature.ts b/packages/backend/src/api/resources/Feature.ts
index 7d1afeb96e9..787f9bb8da4 100644
--- a/packages/backend/src/api/resources/Feature.ts
+++ b/packages/backend/src/api/resources/Feature.ts
@@ -2,6 +2,8 @@ import type { FeatureJSON } from './JSON';
 
 /**
  * The `Feature` object represents a feature of a subscription plan.
+ *
+ * @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 Feature {
   constructor(
diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 52a56b832aa..a53164f0d40 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -826,6 +826,8 @@ export interface CommerceStatementResource extends ClerkResource {
 
 /**
  * The `CommerceStatementGroup` type represents a group of payment items within a statement.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommerceStatementGroup {
   /**
@@ -1131,6 +1133,8 @@ export interface CommerceSubscriptionResource extends ClerkResource {
 
 /**
  * The `CommerceMoneyAmount` type represents a monetary value with currency information.
+ *
+ * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export interface CommerceMoneyAmount {
   /**
@@ -1185,6 +1189,8 @@ export interface CommerceCheckoutTotals {
 
 /**
  * The `CommerceStatementTotals` type represents the total costs, taxes, and other pricing details for a statement.
+ *
+ * @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.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface CommerceStatementTotals extends Omit<CommerceCheckoutTotals, 'totalDueNow'> {}

From 00204364dbdd66f742352eebaf86eb6ea733adf5 Mon Sep 17 00:00:00 2001
From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
Date: Thu, 28 Aug 2025 12:00:11 -0400
Subject: [PATCH 11/13] small structural update

---
 packages/backend/src/api/resources/CommercePlan.ts             | 1 +
 packages/backend/src/api/resources/CommerceSubscription.ts     | 1 +
 packages/backend/src/api/resources/CommerceSubscriptionItem.ts | 1 +
 3 files changed, 3 insertions(+)

diff --git a/packages/backend/src/api/resources/CommercePlan.ts b/packages/backend/src/api/resources/CommercePlan.ts
index 8eec600daf4..0bf708be820 100644
--- a/packages/backend/src/api/resources/CommercePlan.ts
+++ b/packages/backend/src/api/resources/CommercePlan.ts
@@ -5,6 +5,7 @@ import type { CommercePlanJSON } from './JSON';
 
 /**
  * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ *
  * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to pin the SDK version to avoid breaking changes.
  */
 export class CommercePlan {
diff --git a/packages/backend/src/api/resources/CommerceSubscription.ts b/packages/backend/src/api/resources/CommerceSubscription.ts
index ae990060225..9c403b10d94 100644
--- a/packages/backend/src/api/resources/CommerceSubscription.ts
+++ b/packages/backend/src/api/resources/CommerceSubscription.ts
@@ -5,6 +5,7 @@ import type { CommerceSubscriptionJSON } from './JSON';
 
 /**
  * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ *
  * @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 {
diff --git a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
index a19fc2911ed..13e91acbc20 100644
--- a/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
+++ b/packages/backend/src/api/resources/CommerceSubscriptionItem.ts
@@ -5,6 +5,7 @@ import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
  * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items){{ target: '_blank' }} and is not directly accessible from the Frontend API.
+ *
  * @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 CommerceSubscriptionItem {

From 1e1834a86ccd7fa996546f9205e78fa2ecb47a52 Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Fri, 29 Aug 2025 19:52:08 +0300
Subject: [PATCH 12/13] Apply suggestions from code review

---
 packages/types/src/commerce.ts | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index a53164f0d40..31e1c37dff4 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -542,7 +542,7 @@ export type MakeDefaultPaymentSourceParams = WithOptionalOrgType<unknown>;
 /**
  * The `CommercePaymentSourceResource` type represents a payment source for a checkout session.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export interface CommercePaymentSourceResource extends ClerkResource {
   /**
@@ -827,7 +827,7 @@ export interface CommerceStatementResource extends ClerkResource {
 /**
  * The `CommerceStatementGroup` type represents a group of payment items within a statement.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export interface CommerceStatementGroup {
   /**
@@ -1134,7 +1134,7 @@ export interface CommerceSubscriptionResource extends ClerkResource {
 /**
  * The `CommerceMoneyAmount` type represents a monetary value with currency information.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export interface CommerceMoneyAmount {
   /**
@@ -1158,7 +1158,7 @@ export interface CommerceMoneyAmount {
 /**
  * The `CommerceCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export interface CommerceCheckoutTotals {
   /**
@@ -1190,7 +1190,7 @@ export interface CommerceCheckoutTotals {
 /**
  * The `CommerceStatementTotals` type represents the total costs, taxes, and other pricing details for a statement.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface CommerceStatementTotals extends Omit<CommerceCheckoutTotals, 'totalDueNow'> {}
@@ -1226,6 +1226,8 @@ export type CreateCheckoutParams = WithOptionalOrgType<{
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentSourceId`, `paymentToken`, or `useTestCard` should be provided.**
+  *
+  * @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 and the clerk-js version to avoid breaking changes.
  */
 export type ConfirmCheckoutParams = WithOptionalOrgType<
   | {
@@ -1259,7 +1261,7 @@ export type ConfirmCheckoutParams = WithOptionalOrgType<
 /**
  * The `CommerceCheckoutResource` type represents information about a checkout session.
  *
- * @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.
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export interface CommerceCheckoutResource extends ClerkResource {
   /**

From 974fb9df498756f934b5f0281a7ca23e2925e76c Mon Sep 17 00:00:00 2001
From: panteliselef <panteliselef@outlook.com>
Date: Fri, 29 Aug 2025 21:32:27 +0300
Subject: [PATCH 13/13] format

---
 packages/types/src/commerce.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/types/src/commerce.ts b/packages/types/src/commerce.ts
index 71db146b5e8..59973af134f 100644
--- a/packages/types/src/commerce.ts
+++ b/packages/types/src/commerce.ts
@@ -1178,8 +1178,8 @@ export type CreateCheckoutParams = WithOptionalOrgType<{
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentSourceId`, `paymentToken`, or `useTestCard` should be provided.**
-  *
-  * @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 and the clerk-js version to avoid breaking changes.
+ *
+ * @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 and the clerk-js version to avoid breaking changes.
  */
 export type ConfirmCheckoutParams =
   | {