@clerk/shared/dist/types/billing.d.ts

Internal package utils used by the Clerk SDKs

import { ClerkError } from "../errors/clerkError.js";
import { DeletedObjectResource } from "./deletedObject.js";
import { ClerkPaginatedResponse, ClerkPaginationParams } from "./pagination.js";
import { ClerkResource } from "./resource.js";
import { ForceNull, RemoveFunctions, Simplify } from "./utils.js";
import { SetActiveNavigate } from "./clerk.js";

//#region src/types/billing.d.ts
/**
 * Intersects `T` with an optional organization scope (`orgId`) for billing and related requests.
 *
 * @interface
 */
type WithOptionalOrgType<T> = T & {
  /**
   * The Organization ID to perform the request on.
   */
  orgId?: string;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingNamespace {
  /**
   * Gets a list of payment attempts for the current user or supplied Organization.
   * @returns A [`ClerkPaginatedResponse`](/docs/reference/types/clerk-paginated-response) of [`BillingPaymentResource`](/docs/reference/types/billing-payment-resource) objects.
   *
   * @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.
   */
  getPaymentAttempts: (params: GetPaymentAttemptsParams) => Promise<ClerkPaginatedResponse<BillingPaymentResource>>;
  /**
   * Gets details of a specific payment attempt for the current user or supplied Organization.
   * @returns A [`BillingPaymentResource`](https://clerk.com/docs/reference/types/billing-payment-resource) object.
   *
   * @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.
   */
  getPaymentAttempt: (params: GetPaymentAttemptParams) => Promise<BillingPaymentResource>;
  /**
   * Gets a list of all publically visible Billing Plans.
   * @returns A [`ClerkPaginatedResponse`](/docs/reference/types/clerk-paginated-response) of [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) objects.
   *
   * @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.
   */
  getPlans: (params?: GetPlansParams) => Promise<ClerkPaginatedResponse<BillingPlanResource>>;
  /**
   * Gets a given Billing Plan.
   * @returns A [`BillingPlanResource`](/docs/reference/types/billing-plan-resource) object.
   *
   * @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.
   */
  getPlan: (params: GetPlanParams) => Promise<BillingPlanResource>;
  /**
   * Gets the main Billing Subscription for the current user or supplied Organization.
   * @returns A [`BillingSubscriptionResource`](/docs/reference/types/billing-subscription-resource) object.
   *
   * @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.
   */
  getSubscription: (params: GetSubscriptionParams) => Promise<BillingSubscriptionResource>;
  /**
   * Gets a list of Billing Statements for the current user or supplied Organization.
   * @returns A [`ClerkPaginatedResponse`](/docs/reference/types/clerk-paginated-response) of [`BillingStatementResource`](/docs/reference/types/billing-statement-resource) objects.
   *
   * @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.
   */
  getStatements: (params: GetStatementsParams) => Promise<ClerkPaginatedResponse<BillingStatementResource>>;
  /**
   * Gets a given Billing Statement.
   * @returns A [`BillingStatementResource`](/docs/reference/types/billing-statement-resource) object.
   *
   * @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.
   */
  getStatement: (params: GetStatementParams) => Promise<BillingStatementResource>;
  /**
   * Creates a new Billing checkout for the current user or supplied Organization.
   * @returns A [`BillingCheckoutResource`](/docs/reference/types/billing-checkout-resource) object.
   *
   * @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.
   */
  startCheckout: (params: CreateCheckoutParams) => Promise<BillingCheckoutResource>;
  /**
   * Gets the credit balance for the current payer.
   * @returns A [`BillingCreditBalanceResource`](https://clerk.com/docs/reference/types/billing-credit-balance-resource) object.
   *
   * @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.
   */
  getCreditBalance: (params: GetCreditBalanceParams) => Promise<BillingCreditBalanceResource>;
  /**
   * Gets the credit history for the current payer.
   * @returns A [`ClerkPaginatedResponse`](https://clerk.com/docs/reference/types/clerk-paginated-response) of [`BillingCreditLedgerResource`](https://clerk.com/docs/reference/types/billing-credit-ledger-resource) objects.
   *
   * @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.
   */
  getCreditHistory: (params: GetCreditHistoryParams) => Promise<ClerkPaginatedResponse<BillingCreditLedgerResource>>;
}
/**
 * @inline
 *
 * @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.
 */
type BillingPayerResourceType = 'org' | 'user';
/**
 * @inline
 *
 * @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.
 */
type ForPayerType = 'organization' | 'user';
/**
 * @inline
 *
 * @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.
 */
type BillingSubscriptionStatus = 'active' | 'ended' | 'upcoming' | 'past_due';
/**
 * The billing period for the Plan.
 *
 * @inline
 */
type BillingSubscriptionPlanPeriod = 'month' | 'annual';
/**
 * @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.
 */
interface BillingPayerMethods {
  /**
   * Initializes a payment method.
   * @returns A [`BillingInitializedPaymentMethodResource`](https://clerk.com/docs/reference/types/billing-initialized-payment-method-resource) object.
   * @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.
   */
  initializePaymentMethod: (params: InitializePaymentMethodParams) => Promise<BillingInitializedPaymentMethodResource>;
  /**
   * Adds a payment method.
   * @returns A [`BillingPaymentMethodResource`](https://clerk.com/docs/reference/types/billing-payment-method-resource) object.
   * @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.
   */
  addPaymentMethod: (params: AddPaymentMethodParams) => Promise<BillingPaymentMethodResource>;
  /**
   * Gets a list of payment methods that have been stored.
   * @returns A [`ClerkPaginatedResponse`](https://clerk.com/docs/reference/types/clerk-paginated-response) of [`BillingPaymentMethodResource`](https://clerk.com/docs/reference/types/billing-payment-method-resource) objects.
   * @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.
   */
  getPaymentMethods: (params?: GetPaymentMethodsParams) => Promise<ClerkPaginatedResponse<BillingPaymentMethodResource>>;
}
/**
 * @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.
 */
type GetPlanParams = {
  /**
   * The ID of the Billing Plan to get.
   */
  id: string;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type GetPlansParams = ClerkPaginationParams<{
  /**
   * The type of payer for the Plans.
   */
  for?: ForPayerType;
  /**
   * The organization ID to fetch plans for (needs to match the current [Active Organization](!active-organization) ID). Providing this parameter will populate the `availablePrices` field with the prices that are available to the authenticated organization.
   */
  orgId?: string;
  /**
   * The minimum number of seats that the returned plans needs to support.
   */
  minSeats?: number;
}>;
/**
 * The `BillingPlanResource` type represents a Subscription Plan with its details.
 *
 * @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.
 */
interface BillingPlanResource extends ClerkResource {
  /**
   * The unique identifier for the Plan.
   */
  id: string;
  /**
   * The name of the Plan.
   */
  name: string;
  /**
   * The monthly price of the Plan.
   */
  fee: BillingMoneyAmount | null;
  /**
   * The annual price of the Plan or `null` if the Plan is not annual.
   */
  annualFee: BillingMoneyAmount | null;
  /**
   * The effective monthly price when billed annually or `null` if the Plan is not annual.
   */
  annualMonthlyFee: BillingMoneyAmount | null;
  /**
   * A short description of what the Plan offers, or `null` if no description is provided.
   */
  description: string | null;
  /**
   * Whether the Plan is the default Plan.
   */
  isDefault: boolean;
  /**
   * Whether the Plan is recurring.
   */
  isRecurring: boolean;
  /**
   * Whether the Plan has a base fee.
   */
  hasBaseFee: boolean;
  /**
   * Specifies the subscriber type this Plan is designed for.
   *
   * Each Plan is exclusively created for either individual users or Organizations, and cannot be used interchangeably.
   */
  forPayerType: BillingPayerResourceType;
  /**
   * Whether the Plan is visible to the public.
   */
  publiclyVisible: boolean;
  /**
   * The URL-friendly identifier of the Plan.
   */
  slug: string;
  /**
   * The URL of the Plan's avatar image, or `null` if not set.
   */
  avatarUrl: string | null;
  /**
   * The Features the Plan offers.
   */
  features: FeatureResource[];
  /**
   * Per-unit pricing tiers for this Plan (e.g., seats).
   */
  unitPrices?: BillingPlanUnitPrice[];
  /**
   * The prices that are available to be used to checkout for the associated plan. Can be used to select
   * non-default prices.
   */
  availablePrices?: BillingPlanPrice[];
  /**
   * The number of days of the free trial for the Plan. `null` if the Plan does not have a free trial.
   */
  freeTrialDays: number | null;
  /**
   * Whether the Plan has a free trial.
   */
  freeTrialEnabled: boolean;
}
/**
 * The `BillingSubscriptionItemSeats` type represents seat entitlements attached to a subscription item.
 *
 * @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.
 */
interface BillingSubscriptionItemSeats {
  /**
   * The seat limit active while the parent subscription item was active. `null` means unlimited.
   */
  quantity: number | null;
  /**
   * The tier-level breakdown of seats for this subscription item.
   */
  tiers?: BillingPerUnitTotalTier[];
}
/**
 * The `BillingPlanUnitPriceTier` type represents a single pricing tier for a unit type on a plan.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingPlanUnitPriceTier {
  /**
   * The unique identifier of the unit price tier.
   */
  id: string;
  /**
   * The first block number this tier applies to.
   */
  startsAtBlock: number;
  /**
   * The final block this tier applies to. `null` means unlimited.
   */
  endsAfterBlock: number | null;
  /**
   * The fee charged for each block in this tier.
   */
  feePerBlock: BillingMoneyAmount;
}
/**
 * The `BillingPlanUnitPrice` type represents unit pricing for a specific unit type (e.g., seats) on a plan.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingPlanUnitPrice {
  /**
   * The unit name, for example `seats`.
   */
  name: string;
  /**
   * Number of units represented by one billable block.
   */
  blockSize: number;
  /**
   * Tiers that define how each block range is priced.
   */
  tiers: BillingPlanUnitPriceTier[];
}
/**
 * The `BillingPlanPrice` type represents a specific possible price for a given Clerk Billing Plan.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingPlanPrice {
  /** The unique identifier of the price */
  id: string;
  /** The monthly price or `null` if the price is not monthly. */
  fee: BillingMoneyAmount | null;
  /** The effective monthly price when billed annually or `null` if the price is not annual. */
  annualMonthlyFee: BillingMoneyAmount | null;
  /** Whether this price is the default price for the plan it's associated with. */
  isDefault: boolean;
  /** The individual unit prices applicable to this price. */
  unitPrices?: BillingPlanUnitPrice[];
}
/**
 * The `BillingPerUnitTotalTier` type represents the cost breakdown for a single tier in checkout totals.
 *
 * @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.
 */
interface BillingPerUnitTotalTier {
  /** The quantity billed within this tier. `null` means unlimited. */
  quantity: number | null;
  /** The fee charged per block for this tier. */
  feePerBlock: BillingMoneyAmount;
  /** The total billed amount for this tier. */
  total: BillingMoneyAmount;
}
/**
 * The `BillingPerUnitTotal` type represents the per-unit cost breakdown in checkout totals.
 *
 * @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.
 */
interface BillingPerUnitTotal {
  /** The unit name, for example `seats`. */
  name: string;
  /** The number of units represented by one billable block. */
  blockSize: number;
  /** The tiers breakdown for this unit total. */
  tiers: BillingPerUnitTotalTier[];
}
/**
 * The `FeatureResource` type represents a Feature of a Plan.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface FeatureResource extends ClerkResource {
  /** The unique identifier for the Feature. */
  id: string;
  /** The display name of the Feature. */
  name: string;
  /** A short description of what the Feature provides, or `null` if not provided. */
  description: string | null;
  /** A unique, URL-friendly identifier for the Feature. */
  slug: string;
  /** The URL of the Feature's avatar image, or `null` if not set. */
  avatarUrl: string | null;
}
/**
 * The status of a payment method.
 *
 * @inline
 */
type BillingPaymentMethodStatus = 'active' | 'expired' | 'disconnected';
/**
 * @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.
 */
type GetPaymentMethodsParams = ClerkPaginationParams;
/**
 * @inline
 *
 * @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.
 */
type PaymentGateway = 'stripe';
/**
 * @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.
 */
type InitializePaymentMethodParams = {
  /**
   * The payment gateway to use.
   */
  gateway: PaymentGateway;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type AddPaymentMethodParams = {
  /**
   * The payment gateway to use.
   */
  gateway: PaymentGateway;
  /**
   * A token representing payment details, usually from a payment form.
   */
  paymentToken: string;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type RemovePaymentMethodParams = WithOptionalOrgType<unknown>;
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type MakeDefaultPaymentMethodParams = WithOptionalOrgType<unknown>;
/**
 * The `BillingPaymentMethodResource` type represents a payment method for a checkout session.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingPaymentMethodResource extends ClerkResource {
  /**
   * The unique identifier for the payment method.
   */
  id: string;
  /**
   * The last four digits of the payment method.
   */
  last4: string | null;
  /**
   * The type of payment method. For example, `'card'`.
   */
  paymentType?: 'card';
  /**
   * The brand or type of card. For example, `'visa'` or `'mastercard'`.
   */
  cardType: string | null;
  /**
   * Whether the payment method is set as the default for the account.
   */
  isDefault?: boolean;
  /**
   * Whether the payment method can be removed by the user.
   */
  isRemovable?: boolean;
  /**
   * The current status of the payment method.
   */
  status: BillingPaymentMethodStatus;
  /**
   * The type of digital wallet, if applicable. For example, `'apple_pay'`, or `'google_pay'`.
   */
  walletType?: string | null;
  /**
   * The card expiration year, if available.
   */
  expiryYear?: number | null;
  /**
   * The card expiration month, if available.
   */
  expiryMonth?: number | null;
  /**
   * The date the payment method was created, if available.
   */
  createdAt?: Date | null;
  /**
   * The date the payment method was last updated, if available.
   */
  updatedAt?: Date | null;
  /**
   * A function that removes this payment method from the account. Accepts the following parameters:
   * <ul>
   *  <li>`orgId?` (`string`): The ID of the Organization to remove the payment method from.</li>
   * </ul>
   *
   * @param params - The parameters for the remove operation.
   * @returns A promise that resolves to a `DeletedObjectResource` object.
   */
  remove: (params?: RemovePaymentMethodParams) => Promise<DeletedObjectResource>;
  /**
   * A function that sets this payment method as the default for the account. Accepts the following parameters:
   * <ul>
   *  <li>`orgId?` (`string`): The ID of the Organization to set as the default.</li>
   * </ul>
   *
   * @param params - The parameters for the make default operation.
   * @returns A promise that resolves to `null`.
   */
  makeDefault: (params?: MakeDefaultPaymentMethodParams) => Promise<null>;
}
/**
 * The `BillingInitializedPaymentMethodResource` type represents a payment method that has been initialized for checkout session.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingInitializedPaymentMethodResource extends ClerkResource {
  /**
   * A client secret from an external payment provider (such as Stripe) used to complete the payment on the client-side.
   */
  externalClientSecret: string;
  /**
   * The unique identifier for the external payment gateway used for this checkout session.
   */
  externalGatewayId: string;
  /**
   * The order the payment methods will be displayed in when [`<PaymentElement/>`](/docs/nextjs/reference/hooks/use-payment-element#payment-element) renders.
   */
  paymentMethodOrder: string[];
}
/**
 * @inline
 *
 * @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.
 */
type BillingPaymentChargeType = 'checkout' | 'recurring';
/**
 * @inline
 *
 * @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.
 */
type BillingPaymentStatus = 'pending' | 'paid' | 'failed';
/**
 * The `BillingPaymentTotals` type represents the per-payment cost breakdown, including any base fee
 * and per-unit (e.g., seats) subtotals.
 *
 * @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.
 */
interface BillingPaymentTotals {
  /**
   * The price of the items before taxes, credits, or discounts are applied.
   */
  subtotal: BillingMoneyAmount;
  /**
   * The total amount for the payment, including taxes and after credits/discounts are applied.
   */
  grandTotal: BillingMoneyAmount;
  /**
   * The amount of tax included in the payment.
   */
  taxTotal: BillingMoneyAmount;
  /**
   * The flat base fee charged on top of any per-unit fees.
   */
  baseFee?: BillingMoneyAmount | null;
  /**
   * Per-unit cost breakdown for this payment (e.g., seats).
   */
  perUnitTotals?: BillingPerUnitTotal[];
  /**
   * Discounts applied to this payment such as mid-cycle prorated seat discounts. `null` when no discounts apply.
   */
  discounts?: BillingDiscounts | null;
}
/**
 * The `BillingPaymentResource` type represents a payment attempt for a user or Organization.
 *
 * @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.
 */
interface BillingPaymentResource extends ClerkResource {
  /**
   * The unique identifier for the payment.
   */
  id: string;
  /**
   * The amount of the payment.
   */
  amount: BillingMoneyAmount;
  /**
   * The date and time when the payment was successfully completed.
   */
  paidAt: Date | null;
  /**
   * The date and time when the payment failed.
   */
  failedAt: Date | null;
  /**
   * The date and time when the payment was last updated.
   */
  updatedAt: Date;
  /**
   * The payment method being used for the payment, such as credit card or bank account.
   */
  paymentMethod: BillingPaymentMethodResource | null;
  /**
   * The subscription item being paid for.
   */
  subscriptionItem: BillingSubscriptionItemResource;
  /**
   * The type of charge this payment represents. Can be `'checkout'` for one-time payments or `'recurring'` for subscription payments.
   */
  chargeType: BillingPaymentChargeType;
  /**
   * The current status of the payment.
   */
  status: BillingPaymentStatus;
  /**
   * Per-payment breakdown with optional base fee and per-unit (e.g., seats) subtotals.
   * Absent on older responses.
   */
  totals?: BillingPaymentTotals | null;
}
/**
 * @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.
 */
type GetPaymentAttemptsParams = WithOptionalOrgType<ClerkPaginationParams>;
/**
 * @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.
 */
type GetPaymentAttemptParams = {
  /**
   * The unique identifier for the payment attempt to get.
   */
  id: string;
} & WithOptionalOrgType<ClerkPaginationParams>;
/**
 * @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.
 */
type GetStatementParams = {
  /**
   * The ID of the statement to get.
   */
  id: string;
} & WithOptionalOrgType<ClerkPaginationParams>;
/**
 * @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.
 */
type GetStatementsParams = WithOptionalOrgType<ClerkPaginationParams>;
/**
 * @inline
 *
 * @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.
 */
type BillingStatementStatus = 'open' | 'closed';
/**
 * The `BillingStatementResource` type represents a billing statement for a user or Organization.
 *
 * @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.
 */
interface BillingStatementResource extends ClerkResource {
  /**
   * The unique identifier for the statement.
   */
  id: string;
  /**
   * An object containing the financial totals for the statement, including subtotal, grand total, tax total, credit, and past due amounts.
   */
  totals: BillingStatementTotals;
  /**
   * The current status of the statement. Statements can be either `'open'` (still accumulating charges) or `'closed'` (finalized).
   */
  status: BillingStatementStatus;
  /**
   * The date and time when the statement was created or last updated.
   */
  timestamp: Date;
  /**
   * An array of statement groups, where each group contains payment items organized by timestamp.
   */
  groups: BillingStatementGroup[];
}
/**
 * The `BillingStatementGroup` type represents a group of payment items within a statement.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingStatementGroup {
  /**
   * The date and time when this group of payment items was created or last updated.
   */
  timestamp: Date;
  /**
   * An array of payment resources that belong to this group.
   */
  items: BillingPaymentResource[];
}
/**
 * @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.
 */
type GetSubscriptionParams = {
  /**
   * The unique identifier for the Organization to get the subscription for.
   */
  orgId?: string;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type CancelSubscriptionParams = WithOptionalOrgType<unknown>;
/**
 * The `BillingSubscriptionNextPayment` type represents the upcoming payment details for a subscription.
 *
 * @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.
 */
interface BillingSubscriptionNextPayment {
  /**
   * The amount of the next payment.
   */
  amount: BillingMoneyAmount;
  /**
   * The date when the next payment is due.
   */
  date: Date;
  /**
   * Per-unit cost breakdown for the next payment (e.g., seats).
   */
  perUnitTotals?: BillingPerUnitTotal[];
  /**
   * Full cost breakdown for the next payment.
   */
  totals?: BillingTotals;
}
/**
 * The `BillingSubscriptionItemNextPayment` type represents the upcoming payment details for a subscription item.
 *
 * @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.
 */
interface BillingSubscriptionItemNextPayment {
  /**
   * The amount of the next payment.
   */
  amount: BillingMoneyAmount;
  /**
   * The date when the next payment is due.
   */
  date: Date;
  /**
   * Per-unit cost breakdown for the next payment (e.g., seats).
   */
  perUnitTotals?: BillingPerUnitTotal[];
  /**
   * Full cost breakdown for the next payment.
   */
  totals?: BillingTotals;
}
/**
 * The `BillingSubscriptionItemResource` type represents an item in a subscription.
 *
 * @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.
 */
interface BillingSubscriptionItemResource extends ClerkResource {
  /**
   * The unique identifier for the subscription item.
   */
  id: string;
  /**
   * The Plan associated with the subscription item.
   */
  plan: BillingPlanResource;
  /**
   * The billing period for the subscription item.
   */
  planPeriod: BillingSubscriptionPlanPeriod;
  /**
   * The ID of the price that this subscription item is associated with.
   */
  priceId: string;
  /**
   * The status of the subscription item.
   */
  status: BillingSubscriptionStatus;
  /**
   * The date and time when the subscription item was created.
   */
  createdAt: Date;
  /**
   * The date and time when the subscription item became past due. `null` if the subscription item is not past due.
   */
  pastDueAt: Date | null;
  /**
   * The date and time when the current billing period starts.
   */
  periodStart: Date;
  /**
   * The date and time when the current billing period ends. `null` if not set.
   */
  periodEnd: Date | null;
  /**
   * The date and time when the subscription item was canceled. `null` if the subscription item is not canceled.
   */
  canceledAt: Date | null;
  /**
   * The amount charged for the subscription item.
   */
  amount?: BillingMoneyAmount;
  /**
   * Information about the next payment for this subscription item.
   */
  nextPayment?: BillingSubscriptionItemNextPayment | null;
  /**
   * The credit from a previous purchase that is being applied to the subscription item.
   */
  credit?: {
    /**
     * The amount of credit from a previous purchase that is being applied to the subscription item.
     */
    amount: BillingMoneyAmount;
  };
  credits?: BillingCredits;
  /**
   * Seat entitlement details for this subscription item. Only set for organization subscription items with
   * seat-based billing.
   */
  seats?: BillingSubscriptionItemSeats;
  /**
   * A function to cancel the subscription item. Accepts the following parameters:
   * <ul>
   *  <li>`orgId?` (`string`): The ID of the Organization to cancel the subscription item from.</li>
   * </ul>
   *
   * @param params - The parameters for the cancel operation.
   * @returns A promise that resolves to a `DeletedObjectResource` object.
   */
  cancel: (params: CancelSubscriptionParams) => Promise<DeletedObjectResource>;
  /**
   * Whether the subscription item is for a free trial.
   */
  isFreeTrial: boolean;
}
/**
 * The `BillingSubscriptionResource` type represents a subscription to a plan.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingSubscriptionResource extends ClerkResource {
  /**
   * The unique identifier for the subscription.
   */
  id: string;
  /**
   * The date when the subscription became active.
   */
  activeAt: Date;
  /**
   * The date when the subscription was created.
   */
  createdAt: Date;
  /**
   * Information about the next payment, including the amount and the date it's due. Returns null if there is no upcoming payment.
   */
  nextPayment?: BillingSubscriptionNextPayment | null;
  /**
   * The date when the subscription became past due, or `null` if the subscription is not past due.
   */
  pastDueAt: Date | null;
  /**
   * The current status of the subscription. Due to the free plan subscription item, the top level subscription can either be `active` or `past_due`.
   */
  status: Extract<BillingSubscriptionStatus, 'active' | 'past_due'>;
  /**
   * The list of subscription items included in this subscription.
   */
  subscriptionItems: BillingSubscriptionItemResource[];
  /**
   * The date when the subscription was last updated, or `null` if it hasn't been updated.
   */
  updatedAt: Date | null;
  /**
   * Whether the payer is eligible for a free trial.
   */
  eligibleForFreeTrial: boolean;
}
/**
 * The `BillingCreditBalanceResource` type represents the credit balance for a payer.
 * @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.
 */
interface BillingCreditBalanceResource {
  /** The balance of the credit. */
  balance: BillingMoneyAmount | null;
}
/**
 * @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.
 */
type GetCreditBalanceParams = {
  /** The ID of the Organization to get the credit balance for. */orgId?: string;
};
/**
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
type GetCreditHistoryParams = {
  /**
   * The ID of the Organization to get the credit history for.
   */
  orgId?: string;
};
/**
 * The `BillingCreditLedgerResource` type represents a credit ledger entry for the current payer or given Organization.
 * @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.
 */
interface BillingCreditLedgerResource {
  /** The ID of the credit ledger entry. */
  id: string;
  /** The amount of the credit ledger entry. */
  amount: BillingMoneyAmount;
  /** The type of the source of the credit ledger entry. */
  sourceType: string;
  /** The ID of the source of the credit ledger entry. */
  sourceId: string;
  /** The date when the credit ledger entry was created. */
  createdAt: Date;
}
/**
 * The `BillingMoneyAmount` type represents a monetary value with currency information.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingMoneyAmount {
  /**
   * The raw amount as a number, usually in the smallest unit of the currency (like cents for USD). For example, `1000` for $10.00.
   */
  amount: number;
  /**
   * The amount as a formatted string. For example, `10.00` for $10.00.
   */
  amountFormatted: string;
  /**
   * The ISO currency code for this amount. For example, `USD`.
   */
  currency: string;
  /**
   * The symbol for the currency. For example, `$`.
   */
  currencySymbol: string;
}
interface BillingProrationCreditDetail {
  amount: BillingMoneyAmount;
  cycleDaysRemaining: number;
  cycleDaysTotal: number;
  cycleRemainingPercent: number;
}
interface BillingPayerCredit {
  remainingBalance: BillingMoneyAmount;
  appliedAmount: BillingMoneyAmount;
}
interface BillingCredits {
  proration: BillingProrationCreditDetail | null;
  payer: BillingPayerCredit | null;
  total: BillingMoneyAmount;
}
/**
 * Details about a prorated discount applied when adding a seat mid-cycle. The discount covers the part of the
 * billing period that has already passed, so the payer is only charged for the time remaining in the 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.
 */
interface BillingProrationDiscount {
  /**
   * The amount of the proration discount.
   */
  amount: BillingMoneyAmount;
  /**
   * The number of days that have passed in the billing cycle for which this proration discount represents.
   */
  cycleDaysPassed: number;
  /**
   * The total number of days in the billing cycle.
   */
  cycleDaysTotal: number;
  /**
   * The percentage of the billing cycle that has passed.
   */
  cyclePassedPercent: number;
}
/**
 * Discounts applied to the checkout, such as prorated discounts for mid-cycle seat additions.
 *
 * @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.
 */
interface BillingDiscounts {
  /**
   * The prorated discount for the part of the billing period that has already passed when adding a seat mid-cycle.
   * Unlike the proration credit (which refunds the unused remainder of a plan you already paid for), this discount
   * means you are not charged for the portion of the new seat's cycle that has already elapsed.
   */
  proration: BillingProrationDiscount | null;
  /**
   * The total of all discounts applied to the checkout.
   */
  total: BillingMoneyAmount;
}
/**
 * Per-period renewal totals, describing what the subscription renewal charge will look like after the current checkout.
 * Unlike the top-level checkout totals (which only reflect the items actively being purchased),
 * this object contains the full renewal breakdown including all seats and the base plan fee.
 *
 * @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.
 */
interface BillingPeriodTotals {
  /**
   * The subtotal for the billing period.
   */
  subtotal: BillingMoneyAmount;
  /**
   * The base fee for the billing period.
   */
  baseFee: BillingMoneyAmount;
  /**
   * The tax total for the billing period.
   */
  taxTotal: BillingMoneyAmount;
  /**
   * The grand total for the billing period.
   */
  grandTotal: BillingMoneyAmount;
  /**
   * Per-unit cost breakdown for the renewal period, covering all units purchased to date
   * (not just the ones being added in this checkout).
   */
  perUnitTotals?: BillingPerUnitTotal[];
}
/**
 * The `BillingTotals` type represents a granular breakdown of the total amount that will be charged, either during
 * checkout or at renewal.
 *
 * @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.
 */
interface BillingTotals {
  /**
   * Subtotal before adjustments
   */
  subtotal: BillingMoneyAmount;
  /**
   * Base fee component before per-unit charges and adjustments
   */
  baseFee: BillingMoneyAmount | null;
  /**
   * Total tax amount
   */
  taxTotal: BillingMoneyAmount;
  /**
   * Grand total amount
   */
  grandTotal: BillingMoneyAmount;
  /**
   * Total amount due after free trial ends
   */
  totalDueAfterFreeTrial?: BillingMoneyAmount | null;
  /**
   * Credit amount
   */
  credit?: BillingMoneyAmount | null;
  /**
   * Unified credits breakdown
   */
  credits: BillingCredits | null;
  /**
   * Information about the discounts applied to the payment
   */
  discounts: BillingDiscounts | null;
  /**
   * Past due amount
   */
  pastDue?: BillingMoneyAmount | null;
  /**
   * Total amount due now
   */
  totalDueNow?: BillingMoneyAmount;
  /**
   * Per-unit total breakdown (e.g., seats)
   */
  perUnitTotals?: BillingPerUnitTotal[];
  /**
   * Per-period renewal totals, broken down granularly
   */
  totalsDuePerPeriod?: BillingPeriodTotals;
  /**
   * The expected total payment for each future billing period
   */
  totalDuePerPeriod?: BillingMoneyAmount;
}
/**
 * The `BillingCheckoutTotals` type represents the total costs, taxes, and other pricing details for a checkout session.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingCheckoutTotals {
  /**
   * The price of items actively being purchased in this checkout, before taxes and discounts.
   * When only adding seats mid-cycle, this reflects just the new seats and excludes the base plan fee and
   * seats that were already paid for.
   */
  subtotal: BillingMoneyAmount;
  /**
   * The base plan fee portion of the totals, before per-unit charges and adjustments.
   */
  baseFee?: BillingMoneyAmount;
  /**
   * The total amount for the checkout, including taxes and after credits/discounts are applied. This is the final amount due.
   */
  grandTotal: BillingMoneyAmount;
  /**
   * The amount of tax included in the checkout.
   */
  taxTotal: BillingMoneyAmount;
  /**
   * Per-unit cost breakdown for items actively being purchased in this checkout (e.g., seats being added).
   * When only adding seats mid-cycle, this only covers the seats being added, not seats already paid for.
   */
  perUnitTotals?: BillingPerUnitTotal[];
  /**
   * The amount that needs to be immediately paid to complete the checkout.
   */
  totalDueNow: BillingMoneyAmount;
  /**
   * The amount that will be charged per period for this subscription.
   */
  totalDuePerPeriod: BillingMoneyAmount;
  /**
   * Any credits (like account balance or promo credits) that are being applied to the checkout.
   */
  credit: BillingMoneyAmount | null;
  credits: BillingCredits | null;
  /**
   * Any outstanding amount from previous unpaid invoices that is being collected as part of the checkout.
   */
  pastDue: BillingMoneyAmount | null;
  /**
   * The amount that becomes due after a free trial ends.
   */
  totalDueAfterFreeTrial: BillingMoneyAmount | null;
  /**
   * Discounts applied to this checkout such as mid-cycle prorated seat discounts.
   */
  discounts?: BillingDiscounts | null;
  /**
   * Full renewal period totals after this checkout completes.
   * Contains the complete breakdown of what the next recurring charge will look like,
   * including all seats and the base plan fee.
   */
  totalsDuePerPeriod?: BillingPeriodTotals;
}
/**
 * The `BillingStatementTotals` type represents the total costs, taxes, and other pricing details for a statement.
 *
 * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes.
 */
interface BillingStatementTotals {
  /**
   * The price of the items or Plan before taxes, credits, or discounts are applied.
   */
  subtotal: BillingMoneyAmount;
  /**
   * The total amount for the checkout, including taxes and after credits/discounts are applied. This is the final amount due.
   */
  grandTotal: BillingMoneyAmount;
  /**
   * The amount of tax included in the checkout.
   */
  taxTotal: BillingMoneyAmount;
}
/**
 * The `startCheckout()` method accepts the following parameters.
 *
 * @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.
 */
type CreateCheckoutParams = WithOptionalOrgType<{
  /**
   * The unique identifier for the