docs(repo): Fixing billing broken links for Typedoc output

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;
 

.changeset/fix-billing-typedoc-pages.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Fix broken Billing TypeDoc links and add missing JSDoc descriptions for the credit and discount types.

.typedoc/__tests__/relative-link-replacements.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+// @ts-expect-error — .mjs plugin has no type declarations
+import { applyRelativeLinkReplacements } from '../custom-plugin.mjs';
+
+/**
+ * Unit coverage for the `LINK_REPLACEMENTS` rules exercised through the exported
+ * `applyRelativeLinkReplacements()` entry point. These guard the Billing checkout
+ * links so an incorrect route or anchor cannot silently pass CI.
+ */
+describe('applyRelativeLinkReplacements', () => {
+ const cases: Array<[label: string, input: string, expected: string]> = [
+ [
+ 'confirm-checkout-params routes to the #confirm-parameters section',
+ '[x](confirm-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#confirm-parameters)',
+ ],
+ [
+ 'update-checkout-params routes to the #update-parameters section',
+ '[x](update-checkout-params.mdx)',
+ '[x](/docs/reference/types/billing-checkout-resource#update-parameters)',
+ ],
+ [
+ 'preserves an anchor from the source link',
+ '[x](billing-credits.mdx#total)',
+ '[x](/docs/reference/types/billing-credits#total)',
+ ],
+ [
+ 'billing-credits routes to its standalone page',
+ '[x](billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'billing-applied-discount routes to its standalone page',
+ '[x](billing-applied-discount.mdx)',
+ '[x](/docs/reference/types/billing-applied-discount)',
+ ],
+ [
+ 'billing-discount-redemption routes to its standalone page',
+ '[x](billing-discount-redemption.mdx)',
+ '[x](/docs/reference/types/billing-discount-redemption)',
+ ],
+ [
+ 'billing-payer-credit routes to its standalone page',
+ '[x](billing-payer-credit.mdx)',
+ '[x](/docs/reference/types/billing-payer-credit)',
+ ],
+ [
+ 'billing-proration-credit-detail routes to its standalone page',
+ '[x](billing-proration-credit-detail.mdx)',
+ '[x](/docs/reference/types/billing-proration-credit-detail)',
+ ],
+ [
+ 'resolves relative path prefixes',
+ '[x](../../types/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ [
+ 'resolves nested object-doc links',
+ '[x](billing-credits/billing-credits.mdx)',
+ '[x](/docs/reference/types/billing-credits)',
+ ],
+ ];
+
+ it.each(cases)('%s', (_label, input, expected) => {
+ expect(applyRelativeLinkReplacements(input)).toBe(expected);
+ });
+
+ it('routes the two sibling next-payment pages independently', () => {
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-item-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-item-next-payment)',
+ );
+ expect(applyRelativeLinkReplacements('[x](billing-subscription-next-payment.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-subscription-next-payment)',
+ );
+ });
+
+ it('does not rewrite a page whose name is a prefix of a replacement key', () => {
+ // `billing-payer` is a prefix of `billing-payer-credit`, but the `.mdx` boundary
+ // must keep an unrelated `billing-payer-resource.mdx` link from being mis-routed.
+ expect(applyRelativeLinkReplacements('[x](billing-payer-resource.mdx)')).toBe(
+ '[x](/docs/reference/types/billing-payer-resource)',
+ );
+ });
+
+ it('leaves content without matching links untouched', () => {
+ expect(applyRelativeLinkReplacements('no links here')).toBe('no links here');
+ expect(applyRelativeLinkReplacements('')).toBe('');
+ });
+});

.typedoc/custom-plugin.mjs

@@ -21,6 +21,7 @@ const FILES_WITHOUT_HEADINGS = [
  'organization-membership-public-user-data.mdx',
  'checkout-signal-value.mdx',
  'checkout-flow-resource.mdx',
+ 'update-checkout-params.mdx',
  'use-checkout-options.mdx',
  'use-payment-element-return.mdx',
  'use-payment-methods-return.mdx',
@@ -108,26 +109,38 @@ const LINK_REPLACEMENTS = [
  ['invitation', '/docs/reference/backend/types/backend-invitation'],
  ['verify-token-options', '#verify-token-options'],
  ['localization-resource', '/docs/guides/customizing-clerk/localization'],
- ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#parameters'],
+ ['confirm-checkout-params', '/docs/reference/types/billing-checkout-resource#confirm-parameters'],
+ ['update-checkout-params', '/docs/reference/types/billing-checkout-resource#update-parameters'],
+ ['billing-applied-discount', '/docs/reference/types/billing-applied-discount'],
+ ['billing-credits', '/docs/reference/types/billing-credits'],
+ ['billing-discount-redemption', '/docs/reference/types/billing-discount-redemption'],
+ ['billing-discounts', '/docs/reference/types/billing-discounts'],
+ ['billing-payment-totals', '/docs/reference/types/billing-payment-totals'],
  ['billing-payment-method-resource', '/docs/reference/types/billing-payment-method-resource'],
+ ['billing-payer-credit', '/docs/reference/types/billing-payer-credit'],
  ['billing-payer-resource', '/docs/reference/types/billing-payer-resource'],
+ ['billing-period-totals', '/docs/reference/types/billing-period-totals'],
  ['billing-plan-price', '/docs/reference/types/billing-plan-price'],
  ['billing-plan-resource', '/docs/reference/types/billing-plan-resource'],
  ['billing-plan-unit-price', '/docs/reference/types/billing-plan-unit-price'],
  ['billing-plan-unit-price-tier', '/docs/reference/types/billing-plan-unit-price-tier'],
+ ['billing-proration-discount', '/docs/reference/types/billing-proration-discount'],
+ ['billing-proration-credit-detail', '/docs/reference/types/billing-proration-credit-detail'],
  ['billing-checkout-totals', '/docs/reference/types/billing-checkout-totals'],
  ['billing-checkout-resource', '/docs/reference/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/types/billing-money-amount'],
  ['billing-per-unit-total', '/docs/reference/types/billing-per-unit-total'],
  ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
  ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
+ ['billing-subscription-item-next-payment', '/docs/reference/types/billing-subscription-item-next-payment'],
  ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
  ['feature-resource', '/docs/reference/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
  ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
  ['billing-totals', '/docs/reference/types/billing-totals'],
  ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
+ ['billing-subscription-next-payment', '/docs/reference/types/billing-subscription-next-payment'],
  ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
  ['clerk-api-error', '/docs/reference/types/clerk-api-error'],
  ['billing-statement-totals', '/docs/reference/types/billing-statement-totals'],

packages/shared/src/types/billing.ts

@@ -852,6 +852,9 @@ export interface BillingSubscriptionItemResource extends ClerkResource {
  */
  amount: BillingMoneyAmount;
  };
+ /**
+ * The credits applied to this subscription item.
+ */
  credits?: BillingCredits;
  /**
  * The active discount applied to this subscription item.
@@ -994,21 +997,63 @@ export interface BillingMoneyAmount {
  currencySymbol: string;
 }
 
+/**
+ * Contains details about a proration credit, including the remaining portion of the billing cycle.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingProrationCreditDetail {
+ /**
+ * The monetary value of the proration credit.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The number of days remaining in the current billing cycle.
+ */
  cycleDaysRemaining: number;
+ /**
+ * The total number of days in the billing cycle.
+ */
  cycleDaysTotal: number;
+ /**
+ * The percentage of the billing cycle that remains.
+ */
  cycleRemainingPercent: number;
 }
 
+/**
+ * Contains details about the payer's available credit and the amount applied to the transaction.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingPayerCredit {
+ /**
+ * The payer's credit balance remaining after the transaction.
+ */
  remainingBalance: BillingMoneyAmount;
+ /**
+ * The amount of payer credit applied to the transaction.
+ */
  appliedAmount: BillingMoneyAmount;
 }
 
+/**
+ * The `BillingCredits` type represents the credits applied to a checkout or payment.
+ *
+ * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
+ */
 export interface BillingCredits {
+ /**
+ * The credit for the unused portion of the current billing cycle. `null` when no proration credit applies.
+ */
  proration: BillingProrationCreditDetail | null;
+ /**
+ * The payer credit applied to the transaction. `null` when no payer credit applies.
+ */
  payer: BillingPayerCredit | null;
+ /**
+ * The total monetary value of all credits applied to the transaction.
+ */
  total: BillingMoneyAmount;
 }
 
@@ -1043,14 +1088,44 @@ export interface BillingProrationDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingAppliedDiscount {
+ /**
+ * The monetary value of the discount applied to the transaction.
+ */
  amount: BillingMoneyAmount;
+ /**
+ * The unique identifier of the discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The promotion code used to apply the discount.
+ */
  promoCode?: string;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The originally configured duration in billing cycles. `null` means the discount does not expire after a fixed
+ * number of cycles.
+ */
  durationInCycles?: number | null;
 }
 
@@ -1060,20 +1135,67 @@ export interface BillingAppliedDiscount {
  * @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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
 export interface BillingDiscountRedemption {
+ /**
+ * The unique identifier of the discount redemption.
+ */
  id: string;
+ /**
+ * The unique identifier of the subscription item receiving the discount.
+ */
  subscriptionItemId: string;
+ /**
+ * The unique identifier of the redeemed discount.
+ */
  discountId: string;
+ /**
+ * The display name of the discount.
+ */
  name: string;
+ /**
+ * How the discount was applied to the subscription item.
+ */
  source: 'promotion' | 'manual' | 'promo_code';
+ /**
+ * The promotion code used to redeem the discount.
+ */
  promoCode?: string;
+ /**
+ * Whether the discount subtracts a percentage or a fixed amount.
+ */
  effect?: 'percentage' | 'fixed_amount';
+ /**
+ * The percentage deducted when `effect` is `'percentage'`.
+ */
  percentOff?: number;
+ /**
+ * The configured fixed amount off when `effect` is `'fixed_amount'`. This is the discount's configured value, which
+ * can differ from the `amount` actually applied to the transaction.
+ */
  amountOff?: BillingMoneyAmount;
+ /**
+ * The monetary value of the discount applied to the subscription item.
+ */
  amount?: BillingMoneyAmount;
+ /**
+ * The number of billing cycles for which the discount remains active. `null` means the discount does not expire
+ * after a fixed number of cycles.
+ */
  cyclesRemaining: number | null;
+ /**
+ * The number of billing cycles to which the discount has already been applied.
+ */
  cyclesApplied: number;
+ /**
+ * The current status of the discount redemption.
+ */
  status?: 'active' | 'exhausted' | 'removed';
+ /**
+ * The date and time when the discount was redeemed.
+ */
  redeemedAt: Date;
+ /**
+ * The identifier of the user who redeemed the discount. `null` if no user was recorded.
+ */
  redeemedBy: string | null;
 }
 
@@ -1232,6 +1354,9 @@ export interface BillingCheckoutTotals {
  * Any credits (like account balance or promo credits) that are being applied to the checkout.
  */
  credit: BillingMoneyAmount | null;
+ /**
+ * The credits applied to the checkout. `null` when no credits apply.
+ */
  credits: BillingCredits | null;
  /**
  * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
@@ -1302,16 +1427,20 @@ 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](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
  */
-export type UpdateCheckoutParams = WithOptionalOrgType<{
+export type UpdateCheckoutParams = {
  /**
  * The unique identifier for the checkout session.
  */
  id: string;
+ /**
+ * The Organization ID to perform the request on.
+ */
+ orgId?: string;
  /**
  * The promo code to apply. Use an empty string to remove the applied promo code.
  */
  promoCode: string;
-}>;
+};
 
 /**
  * The `confirm()` method accepts the following parameters. **Only one of `paymentMethodId`, `paymentToken`, or `useTestCard` should be provided.**
@@ -1392,7 +1521,7 @@ export interface BillingCheckoutResource extends ClerkResource {
  */
  totals: BillingTotals;
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
@@ -1542,12 +1671,12 @@ export interface CheckoutFlowFinalizeParams {
  */
 interface CheckoutFlowMethods {
  /**
- * Updates the current checkout. Use an empty promo code to remove the applied promo code.
+ * Updates the current checkout. Use an empty promo code to remove the applied promo code. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#update)
  */
  update: (params: Pick<UpdateCheckoutParams, 'promoCode'>) => Promise<{ error: ClerkError | null }>;
 
  /**
- * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](#confirm)
+ * A function to confirm and finalize the checkout process, usually after payment information has been provided and validated. [Learn more.](https://clerk.com/docs/reference/types/billing-checkout-resource#confirm)
  */
  confirm: (params: ConfirmCheckoutParams) => Promise<{ error: ClerkError | null }>;