@stigg/typescript 0.1.0-beta.2 → 0.1.0-beta.21

package/src/resources/v1/plans/plans.ts

@@ -6,6 +6,7 @@ import {
   EntitlementCreateParams,
   EntitlementCreateResponse,
   EntitlementDeleteParams,
+  EntitlementListParams,
   EntitlementListResponse,
   EntitlementUpdateParams,
   Entitlements,
@@ -13,6 +14,7 @@ import {
 } from './entitlements';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -24,68 +26,293 @@ export class Plans extends APIResource {
 
   /**
    * Creates a new plan in draft status.
+   *
+   * @example
+   * ```ts
+   * const plan = await client.v1.plans.create({
+   *   id: 'id',
+   *   displayName: 'displayName',
+   *   productId: 'productId',
+   * });
+   * ```
    */
-  create(body: PlanCreateParams, options?: RequestOptions): APIPromise<Plan> {
-    return this._client.post('/api/v1/plans', { body, ...options });
+  create(params: PlanCreateParams, options?: RequestOptions): APIPromise<Plan> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/plans', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Retrieves a plan by its unique identifier, including entitlements and pricing
    * details.
+   *
+   * @example
+   * ```ts
+   * const plan = await client.v1.plans.retrieve('x');
+   * ```
    */
-  retrieve(id: string, options?: RequestOptions): APIPromise<Plan> {
-    return this._client.get(path`/api/v1/plans/${id}`, options);
+  retrieve(
+    id: string,
+    params: PlanRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Plan> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params ?? {};
+    return this._client.get(path`/api/v1/plans/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Updates an existing plan's properties such as display name, description, and
    * metadata.
+   *
+   * @example
+   * ```ts
+   * const plan = await client.v1.plans.update('x');
+   * ```
    */
-  update(id: string, body: PlanUpdateParams, options?: RequestOptions): APIPromise<Plan> {
-    return this._client.patch(path`/api/v1/plans/${id}`, { body, ...options });
+  update(id: string, params: PlanUpdateParams, options?: RequestOptions): APIPromise<Plan> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.patch(path`/api/v1/plans/${id}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Retrieves a paginated list of plans in the environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListResponse of client.v1.plans.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
-    query: PlanListParams | null | undefined = {},
+    params: PlanListParams | null | undefined = {},
     options?: RequestOptions,
   ): PagePromise<PlanListResponsesMyCursorIDPage, PlanListResponse> {
-    return this._client.getAPIList('/api/v1/plans', MyCursorIDPage<PlanListResponse>, { query, ...options });
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList('/api/v1/plans', MyCursorIDPage<PlanListResponse>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Archives a plan, preventing it from being used in new subscriptions.
+   *
+   * @example
+   * ```ts
+   * const plan = await client.v1.plans.archive('x');
+   * ```
    */
-  archive(id: string, options?: RequestOptions): APIPromise<Plan> {
-    return this._client.post(path`/api/v1/plans/${id}/archive`, options);
+  archive(
+    id: string,
+    params: PlanArchiveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Plan> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params ?? {};
+    return this._client.post(path`/api/v1/plans/${id}/archive`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Creates a draft version of an existing plan for modification before publishing.
+   *
+   * @example
+   * ```ts
+   * const plan = await client.v1.plans.createDraft('x');
+   * ```
+   */
+  createDraft(
+    id: string,
+    params: PlanCreateDraftParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Plan> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params ?? {};
+    return this._client.post(path`/api/v1/plans/${id}/draft`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves the list of charges configured on a plan.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListChargesResponse of client.v1.plans.listCharges(
+   *   'x',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  listCharges(
+    id: string,
+    params: PlanListChargesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PlanListChargesResponsesMyCursorIDPage, PlanListChargesResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList(
+      path`/api/v1/plans/${id}/charges`,
+      MyCursorIDPage<PlanListChargesResponse>,
+      {
+        query,
+        ...options,
+        headers: buildHeaders([
+          {
+            ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+            ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+          },
+          options?.headers,
+        ]),
+      },
+    );
+  }
+
+  /**
+   * Retrieves the list of overage charges configured on a plan.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const planListOverageChargesResponse of client.v1.plans.listOverageCharges(
+   *   'x',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
-  createDraft(id: string, options?: RequestOptions): APIPromise<Plan> {
-    return this._client.post(path`/api/v1/plans/${id}/draft`, options);
+  listOverageCharges(
+    id: string,
+    params: PlanListOverageChargesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<PlanListOverageChargesResponsesMyCursorIDPage, PlanListOverageChargesResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList(
+      path`/api/v1/plans/${id}/overage-charges`,
+      MyCursorIDPage<PlanListOverageChargesResponse>,
+      {
+        query,
+        ...options,
+        headers: buildHeaders([
+          {
+            ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+            ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+          },
+          options?.headers,
+        ]),
+      },
+    );
   }
 
   /**
    * Publishes a draft plan, making it available for use in subscriptions.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.plans.publish('x', {
+   *   migrationType: 'NEW_CUSTOMERS',
+   * });
+   * ```
    */
-  publish(id: string, body: PlanPublishParams, options?: RequestOptions): APIPromise<PlanPublishResponse> {
-    return this._client.post(path`/api/v1/plans/${id}/publish`, { body, ...options });
+  publish(id: string, params: PlanPublishParams, options?: RequestOptions): APIPromise<PlanPublishResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post(path`/api/v1/plans/${id}/publish`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Removes a draft version of a plan.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.plans.removeDraft('x');
+   * ```
    */
-  removeDraft(id: string, options?: RequestOptions): APIPromise<PlanRemoveDraftResponse> {
-    return this._client.delete(path`/api/v1/plans/${id}/draft`, options);
+  removeDraft(
+    id: string,
+    params: PlanRemoveDraftParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PlanRemoveDraftResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params ?? {};
+    return this._client.delete(path`/api/v1/plans/${id}/draft`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 }
 
 export type PlanListResponsesMyCursorIDPage = MyCursorIDPage<PlanListResponse>;
 
+export type PlanListChargesResponsesMyCursorIDPage = MyCursorIDPage<PlanListChargesResponse>;
+
+export type PlanListOverageChargesResponsesMyCursorIDPage = MyCursorIDPage<PlanListOverageChargesResponse>;
+
 /**
  * Response object
  */
@@ -374,6 +601,1094 @@ export namespace PlanListResponse {
   }
 }
 
+/**
+ * A single pricing row on a plan or addon. Each charge encodes one (billingPeriod,
+ * billingModel, billingCadence, billingCountryCode) combination. Plans and addons
+ * own many of these — one per currency / billing period / feature.
+ */
+export interface PlanListChargesResponse {
+  /**
+   * Unique identifier of the charge
+   */
+  id: string;
+
+  /**
+   * The billing cadence (RECURRING or ONE_OFF)
+   */
+  billingCadence: 'RECURRING' | 'ONE_OFF';
+
+  /**
+   * The billing model (FLAT_FEE, PER_UNIT, USAGE_BASED, CREDIT_BASED, MINIMUM_SPEND)
+   */
+  billingModel: 'FLAT_FEE' | 'MINIMUM_SPEND' | 'PER_UNIT' | 'USAGE_BASED' | 'CREDIT_BASED';
+
+  /**
+   * The billing period (MONTHLY or ANNUALLY)
+   */
+  billingPeriod: 'MONTHLY' | 'ANNUALLY';
+
+  /**
+   * Timestamp when the charge was created
+   */
+  createdAt: string;
+
+  /**
+   * ISO country code for localized pricing, if any
+   */
+  billingCountryCode?: string | null;
+
+  /**
+   * Identifier in the external billing integration (e.g. Stripe price id), if any
+   */
+  billingId?: string | null;
+
+  /**
+   * Block size for usage-based pricing
+   */
+  blockSize?: number | null;
+
+  /**
+   * When credits are granted (for credit-based pricing)
+   */
+  creditGrantCadence?: 'BEGINNING_OF_BILLING_PERIOD' | 'MONTHLY' | null;
+
+  /**
+   * Credit rate configuration for credit-based pricing
+   */
+  creditRate?: PlanListChargesResponse.CreditRate | null;
+
+  /**
+   * Identifier in the linked CRM, if any
+   */
+  crmId?: string | null;
+
+  /**
+   * Deep link to the charge in the linked CRM, if any
+   */
+  crmLinkUrl?: string | null;
+
+  /**
+   * The feature this charge meters, if metered
+   */
+  featureId?: string | null;
+
+  /**
+   * Maximum unit quantity that can be purchased
+   */
+  maxUnitQuantity?: number | null;
+
+  /**
+   * Minimum unit quantity that can be purchased
+   */
+  minUnitQuantity?: number | null;
+
+  /**
+   * The flat price amount and currency, when applicable
+   */
+  price?: PlanListChargesResponse.Price | null;
+
+  /**
+   * Tiered pricing rows when the charge is tiered
+   */
+  tiers?: Array<PlanListChargesResponse.Tier> | null;
+
+  /**
+   * Tiered pricing mode (VOLUME or GRADUATED) when the charge is tiered
+   */
+  tiersMode?: 'VOLUME' | 'GRADUATED' | null;
+
+  /**
+   * Custom currency identifier for top-up pricing, if any
+   */
+  topUpCustomCurrencyId?: string | null;
+
+  /**
+   * True if this charge is referenced by at least one subscription
+   */
+  usedInSubscriptions?: boolean | null;
+}
+
+export namespace PlanListChargesResponse {
+  /**
+   * Credit rate configuration for credit-based pricing
+   */
+  export interface CreditRate {
+    /**
+     * Credit rate amount
+     */
+    amount: number;
+
+    /**
+     * Custom currency identifier
+     */
+    currencyId: string;
+
+    /**
+     * Optional cost formula expression
+     */
+    costFormula?: string | null;
+  }
+
+  /**
+   * The flat price amount and currency, when applicable
+   */
+  export interface Price {
+    /**
+     * The price amount
+     */
+    amount: number;
+
+    /**
+     * ISO 4217 currency code
+     */
+    currency:
+      | 'usd'
+      | 'aed'
+      | 'all'
+      | 'amd'
+      | 'ang'
+      | 'aud'
+      | 'awg'
+      | 'azn'
+      | 'bam'
+      | 'bbd'
+      | 'bdt'
+      | 'bgn'
+      | 'bif'
+      | 'bmd'
+      | 'bnd'
+      | 'bsd'
+      | 'bwp'
+      | 'byn'
+      | 'bzd'
+      | 'brl'
+      | 'cad'
+      | 'cdf'
+      | 'chf'
+      | 'cny'
+      | 'czk'
+      | 'dkk'
+      | 'dop'
+      | 'dzd'
+      | 'egp'
+      | 'etb'
+      | 'eur'
+      | 'fjd'
+      | 'gbp'
+      | 'gel'
+      | 'gip'
+      | 'gmd'
+      | 'gyd'
+      | 'hkd'
+      | 'hrk'
+      | 'htg'
+      | 'idr'
+      | 'ils'
+      | 'inr'
+      | 'isk'
+      | 'jmd'
+      | 'jpy'
+      | 'kes'
+      | 'kgs'
+      | 'khr'
+      | 'kmf'
+      | 'krw'
+      | 'kyd'
+      | 'kzt'
+      | 'lbp'
+      | 'lkr'
+      | 'lrd'
+      | 'lsl'
+      | 'mad'
+      | 'mdl'
+      | 'mga'
+      | 'mkd'
+      | 'mmk'
+      | 'mnt'
+      | 'mop'
+      | 'mro'
+      | 'mvr'
+      | 'mwk'
+      | 'mxn'
+      | 'myr'
+      | 'mzn'
+      | 'nad'
+      | 'ngn'
+      | 'nok'
+      | 'npr'
+      | 'nzd'
+      | 'pgk'
+      | 'php'
+      | 'pkr'
+      | 'pln'
+      | 'qar'
+      | 'ron'
+      | 'rsd'
+      | 'rub'
+      | 'rwf'
+      | 'sar'
+      | 'sbd'
+      | 'scr'
+      | 'sek'
+      | 'sgd'
+      | 'sle'
+      | 'sll'
+      | 'sos'
+      | 'szl'
+      | 'thb'
+      | 'tjs'
+      | 'top'
+      | 'try'
+      | 'ttd'
+      | 'tzs'
+      | 'uah'
+      | 'uzs'
+      | 'vnd'
+      | 'vuv'
+      | 'wst'
+      | 'xaf'
+      | 'xcd'
+      | 'yer'
+      | 'zar'
+      | 'zmw'
+      | 'clp'
+      | 'djf'
+      | 'gnf'
+      | 'ugx'
+      | 'pyg'
+      | 'xof'
+      | 'xpf';
+  }
+
+  /**
+   * A single tier within a tiered charge
+   */
+  export interface Tier {
+    /**
+     * Flat price for this tier
+     */
+    flatPrice?: Tier.FlatPrice | null;
+
+    /**
+     * Per-unit price in this tier
+     */
+    unitPrice?: Tier.UnitPrice | null;
+
+    /**
+     * Upper bound of this tier (null for unlimited)
+     */
+    upTo?: number | null;
+  }
+
+  export namespace Tier {
+    /**
+     * Flat price for this tier
+     */
+    export interface FlatPrice {
+      /**
+       * The price amount
+       */
+      amount: number;
+
+      /**
+       * ISO 4217 currency code
+       */
+      currency:
+        | 'usd'
+        | 'aed'
+        | 'all'
+        | 'amd'
+        | 'ang'
+        | 'aud'
+        | 'awg'
+        | 'azn'
+        | 'bam'
+        | 'bbd'
+        | 'bdt'
+        | 'bgn'
+        | 'bif'
+        | 'bmd'
+        | 'bnd'
+        | 'bsd'
+        | 'bwp'
+        | 'byn'
+        | 'bzd'
+        | 'brl'
+        | 'cad'
+        | 'cdf'
+        | 'chf'
+        | 'cny'
+        | 'czk'
+        | 'dkk'
+        | 'dop'
+        | 'dzd'
+        | 'egp'
+        | 'etb'
+        | 'eur'
+        | 'fjd'
+        | 'gbp'
+        | 'gel'
+        | 'gip'
+        | 'gmd'
+        | 'gyd'
+        | 'hkd'
+        | 'hrk'
+        | 'htg'
+        | 'idr'
+        | 'ils'
+        | 'inr'
+        | 'isk'
+        | 'jmd'
+        | 'jpy'
+        | 'kes'
+        | 'kgs'
+        | 'khr'
+        | 'kmf'
+        | 'krw'
+        | 'kyd'
+        | 'kzt'
+        | 'lbp'
+        | 'lkr'
+        | 'lrd'
+        | 'lsl'
+        | 'mad'
+        | 'mdl'
+        | 'mga'
+        | 'mkd'
+        | 'mmk'
+        | 'mnt'
+        | 'mop'
+        | 'mro'
+        | 'mvr'
+        | 'mwk'
+        | 'mxn'
+        | 'myr'
+        | 'mzn'
+        | 'nad'
+        | 'ngn'
+        | 'nok'
+        | 'npr'
+        | 'nzd'
+        | 'pgk'
+        | 'php'
+        | 'pkr'
+        | 'pln'
+        | 'qar'
+        | 'ron'
+        | 'rsd'
+        | 'rub'
+        | 'rwf'
+        | 'sar'
+        | 'sbd'
+        | 'scr'
+        | 'sek'
+        | 'sgd'
+        | 'sle'
+        | 'sll'
+        | 'sos'
+        | 'szl'
+        | 'thb'
+        | 'tjs'
+        | 'top'
+        | 'try'
+        | 'ttd'
+        | 'tzs'
+        | 'uah'
+        | 'uzs'
+        | 'vnd'
+        | 'vuv'
+        | 'wst'
+        | 'xaf'
+        | 'xcd'
+        | 'yer'
+        | 'zar'
+        | 'zmw'
+        | 'clp'
+        | 'djf'
+        | 'gnf'
+        | 'ugx'
+        | 'pyg'
+        | 'xof'
+        | 'xpf';
+    }
+
+    /**
+     * Per-unit price in this tier
+     */
+    export interface UnitPrice {
+      /**
+       * The price amount
+       */
+      amount: number;
+
+      /**
+       * ISO 4217 currency code
+       */
+      currency:
+        | 'usd'
+        | 'aed'
+        | 'all'
+        | 'amd'
+        | 'ang'
+        | 'aud'
+        | 'awg'
+        | 'azn'
+        | 'bam'
+        | 'bbd'
+        | 'bdt'
+        | 'bgn'
+        | 'bif'
+        | 'bmd'
+        | 'bnd'
+        | 'bsd'
+        | 'bwp'
+        | 'byn'
+        | 'bzd'
+        | 'brl'
+        | 'cad'
+        | 'cdf'
+        | 'chf'
+        | 'cny'
+        | 'czk'
+        | 'dkk'
+        | 'dop'
+        | 'dzd'
+        | 'egp'
+        | 'etb'
+        | 'eur'
+        | 'fjd'
+        | 'gbp'
+        | 'gel'
+        | 'gip'
+        | 'gmd'
+        | 'gyd'
+        | 'hkd'
+        | 'hrk'
+        | 'htg'
+        | 'idr'
+        | 'ils'
+        | 'inr'
+        | 'isk'
+        | 'jmd'
+        | 'jpy'
+        | 'kes'
+        | 'kgs'
+        | 'khr'
+        | 'kmf'
+        | 'krw'
+        | 'kyd'
+        | 'kzt'
+        | 'lbp'
+        | 'lkr'
+        | 'lrd'
+        | 'lsl'
+        | 'mad'
+        | 'mdl'
+        | 'mga'
+        | 'mkd'
+        | 'mmk'
+        | 'mnt'
+        | 'mop'
+        | 'mro'
+        | 'mvr'
+        | 'mwk'
+        | 'mxn'
+        | 'myr'
+        | 'mzn'
+        | 'nad'
+        | 'ngn'
+        | 'nok'
+        | 'npr'
+        | 'nzd'
+        | 'pgk'
+        | 'php'
+        | 'pkr'
+        | 'pln'
+        | 'qar'
+        | 'ron'
+        | 'rsd'
+        | 'rub'
+        | 'rwf'
+        | 'sar'
+        | 'sbd'
+        | 'scr'
+        | 'sek'
+        | 'sgd'
+        | 'sle'
+        | 'sll'
+        | 'sos'
+        | 'szl'
+        | 'thb'
+        | 'tjs'
+        | 'top'
+        | 'try'
+        | 'ttd'
+        | 'tzs'
+        | 'uah'
+        | 'uzs'
+        | 'vnd'
+        | 'vuv'
+        | 'wst'
+        | 'xaf'
+        | 'xcd'
+        | 'yer'
+        | 'zar'
+        | 'zmw'
+        | 'clp'
+        | 'djf'
+        | 'gnf'
+        | 'ugx'
+        | 'pyg'
+        | 'xof'
+        | 'xpf';
+    }
+  }
+}
+
+/**
+ * A single pricing row on a plan or addon. Each charge encodes one (billingPeriod,
+ * billingModel, billingCadence, billingCountryCode) combination. Plans and addons
+ * own many of these — one per currency / billing period / feature.
+ */
+export interface PlanListOverageChargesResponse {
+  /**
+   * Unique identifier of the charge
+   */
+  id: string;
+
+  /**
+   * The billing cadence (RECURRING or ONE_OFF)
+   */
+  billingCadence: 'RECURRING' | 'ONE_OFF';
+
+  /**
+   * The billing model (FLAT_FEE, PER_UNIT, USAGE_BASED, CREDIT_BASED, MINIMUM_SPEND)
+   */
+  billingModel: 'FLAT_FEE' | 'MINIMUM_SPEND' | 'PER_UNIT' | 'USAGE_BASED' | 'CREDIT_BASED';
+
+  /**
+   * The billing period (MONTHLY or ANNUALLY)
+   */
+  billingPeriod: 'MONTHLY' | 'ANNUALLY';
+
+  /**
+   * Timestamp when the charge was created
+   */
+  createdAt: string;
+
+  /**
+   * ISO country code for localized pricing, if any
+   */
+  billingCountryCode?: string | null;
+
+  /**
+   * Identifier in the external billing integration (e.g. Stripe price id), if any
+   */
+  billingId?: string | null;
+
+  /**
+   * Block size for usage-based pricing
+   */
+  blockSize?: number | null;
+
+  /**
+   * When credits are granted (for credit-based pricing)
+   */
+  creditGrantCadence?: 'BEGINNING_OF_BILLING_PERIOD' | 'MONTHLY' | null;
+
+  /**
+   * Credit rate configuration for credit-based pricing
+   */
+  creditRate?: PlanListOverageChargesResponse.CreditRate | null;
+
+  /**
+   * Identifier in the linked CRM, if any
+   */
+  crmId?: string | null;
+
+  /**
+   * Deep link to the charge in the linked CRM, if any
+   */
+  crmLinkUrl?: string | null;
+
+  /**
+   * The feature this charge meters, if metered
+   */
+  featureId?: string | null;
+
+  /**
+   * Maximum unit quantity that can be purchased
+   */
+  maxUnitQuantity?: number | null;
+
+  /**
+   * Minimum unit quantity that can be purchased
+   */
+  minUnitQuantity?: number | null;
+
+  /**
+   * The flat price amount and currency, when applicable
+   */
+  price?: PlanListOverageChargesResponse.Price | null;
+
+  /**
+   * Tiered pricing rows when the charge is tiered
+   */
+  tiers?: Array<PlanListOverageChargesResponse.Tier> | null;
+
+  /**
+   * Tiered pricing mode (VOLUME or GRADUATED) when the charge is tiered
+   */
+  tiersMode?: 'VOLUME' | 'GRADUATED' | null;
+
+  /**
+   * Custom currency identifier for top-up pricing, if any
+   */
+  topUpCustomCurrencyId?: string | null;
+
+  /**
+   * True if this charge is referenced by at least one subscription
+   */
+  usedInSubscriptions?: boolean | null;
+}
+
+export namespace PlanListOverageChargesResponse {
+  /**
+   * Credit rate configuration for credit-based pricing
+   */
+  export interface CreditRate {
+    /**
+     * Credit rate amount
+     */
+    amount: number;
+
+    /**
+     * Custom currency identifier
+     */
+    currencyId: string;
+
+    /**
+     * Optional cost formula expression
+     */
+    costFormula?: string | null;
+  }
+
+  /**
+   * The flat price amount and currency, when applicable
+   */
+  export interface Price {
+    /**
+     * The price amount
+     */
+    amount: number;
+
+    /**
+     * ISO 4217 currency code
+     */
+    currency:
+      | 'usd'
+      | 'aed'
+      | 'all'
+      | 'amd'
+      | 'ang'
+      | 'aud'
+      | 'awg'
+      | 'azn'
+      | 'bam'
+      | 'bbd'
+      | 'bdt'
+      | 'bgn'
+      | 'bif'
+      | 'bmd'
+      | 'bnd'
+      | 'bsd'
+      | 'bwp'
+      | 'byn'
+      | 'bzd'
+      | 'brl'
+      | 'cad'
+      | 'cdf'
+      | 'chf'
+      | 'cny'
+      | 'czk'
+      | 'dkk'
+      | 'dop'
+      | 'dzd'
+      | 'egp'
+      | 'etb'
+      | 'eur'
+      | 'fjd'
+      | 'gbp'
+      | 'gel'
+      | 'gip'
+      | 'gmd'
+      | 'gyd'
+      | 'hkd'
+      | 'hrk'
+      | 'htg'
+      | 'idr'
+      | 'ils'
+      | 'inr'
+      | 'isk'
+      | 'jmd'
+      | 'jpy'
+      | 'kes'
+      | 'kgs'
+      | 'khr'
+      | 'kmf'
+      | 'krw'
+      | 'kyd'
+      | 'kzt'
+      | 'lbp'
+      | 'lkr'
+      | 'lrd'
+      | 'lsl'
+      | 'mad'
+      | 'mdl'
+      | 'mga'
+      | 'mkd'
+      | 'mmk'
+      | 'mnt'
+      | 'mop'
+      | 'mro'
+      | 'mvr'
+      | 'mwk'
+      | 'mxn'
+      | 'myr'
+      | 'mzn'
+      | 'nad'
+      | 'ngn'
+      | 'nok'
+      | 'npr'
+      | 'nzd'
+      | 'pgk'
+      | 'php'
+      | 'pkr'
+      | 'pln'
+      | 'qar'
+      | 'ron'
+      | 'rsd'
+      | 'rub'
+      | 'rwf'
+      | 'sar'
+      | 'sbd'
+      | 'scr'
+      | 'sek'
+      | 'sgd'
+      | 'sle'
+      | 'sll'
+      | 'sos'
+      | 'szl'
+      | 'thb'
+      | 'tjs'
+      | 'top'
+      | 'try'
+      | 'ttd'
+      | 'tzs'
+      | 'uah'
+      | 'uzs'
+      | 'vnd'
+      | 'vuv'
+      | 'wst'
+      | 'xaf'
+      | 'xcd'
+      | 'yer'
+      | 'zar'
+      | 'zmw'
+      | 'clp'
+      | 'djf'
+      | 'gnf'
+      | 'ugx'
+      | 'pyg'
+      | 'xof'
+      | 'xpf';
+  }
+
+  /**
+   * A single tier within a tiered charge
+   */
+  export interface Tier {
+    /**
+     * Flat price for this tier
+     */
+    flatPrice?: Tier.FlatPrice | null;
+
+    /**
+     * Per-unit price in this tier
+     */
+    unitPrice?: Tier.UnitPrice | null;
+
+    /**
+     * Upper bound of this tier (null for unlimited)
+     */
+    upTo?: number | null;
+  }
+
+  export namespace Tier {
+    /**
+     * Flat price for this tier
+     */
+    export interface FlatPrice {
+      /**
+       * The price amount
+       */
+      amount: number;
+
+      /**
+       * ISO 4217 currency code
+       */
+      currency:
+        | 'usd'
+        | 'aed'
+        | 'all'
+        | 'amd'
+        | 'ang'
+        | 'aud'
+        | 'awg'
+        | 'azn'
+        | 'bam'
+        | 'bbd'
+        | 'bdt'
+        | 'bgn'
+        | 'bif'
+        | 'bmd'
+        | 'bnd'
+        | 'bsd'
+        | 'bwp'
+        | 'byn'
+        | 'bzd'
+        | 'brl'
+        | 'cad'
+        | 'cdf'
+        | 'chf'
+        | 'cny'
+        | 'czk'
+        | 'dkk'
+        | 'dop'
+        | 'dzd'
+        | 'egp'
+        | 'etb'
+        | 'eur'
+        | 'fjd'
+        | 'gbp'
+        | 'gel'
+        | 'gip'
+        | 'gmd'
+        | 'gyd'
+        | 'hkd'
+        | 'hrk'
+        | 'htg'
+        | 'idr'
+        | 'ils'
+        | 'inr'
+        | 'isk'
+        | 'jmd'
+        | 'jpy'
+        | 'kes'
+        | 'kgs'
+        | 'khr'
+        | 'kmf'
+        | 'krw'
+        | 'kyd'
+        | 'kzt'
+        | 'lbp'
+        | 'lkr'
+        | 'lrd'
+        | 'lsl'
+        | 'mad'
+        | 'mdl'
+        | 'mga'
+        | 'mkd'
+        | 'mmk'
+        | 'mnt'
+        | 'mop'
+        | 'mro'
+        | 'mvr'
+        | 'mwk'
+        | 'mxn'
+        | 'myr'
+        | 'mzn'
+        | 'nad'
+        | 'ngn'
+        | 'nok'
+        | 'npr'
+        | 'nzd'
+        | 'pgk'
+        | 'php'
+        | 'pkr'
+        | 'pln'
+        | 'qar'
+        | 'ron'
+        | 'rsd'
+        | 'rub'
+        | 'rwf'
+        | 'sar'
+        | 'sbd'
+        | 'scr'
+        | 'sek'
+        | 'sgd'
+        | 'sle'
+        | 'sll'
+        | 'sos'
+        | 'szl'
+        | 'thb'
+        | 'tjs'
+        | 'top'
+        | 'try'
+        | 'ttd'
+        | 'tzs'
+        | 'uah'
+        | 'uzs'
+        | 'vnd'
+        | 'vuv'
+        | 'wst'
+        | 'xaf'
+        | 'xcd'
+        | 'yer'
+        | 'zar'
+        | 'zmw'
+        | 'clp'
+        | 'djf'
+        | 'gnf'
+        | 'ugx'
+        | 'pyg'
+        | 'xof'
+        | 'xpf';
+    }
+
+    /**
+     * Per-unit price in this tier
+     */
+    export interface UnitPrice {
+      /**
+       * The price amount
+       */
+      amount: number;
+
+      /**
+       * ISO 4217 currency code
+       */
+      currency:
+        | 'usd'
+        | 'aed'
+        | 'all'
+        | 'amd'
+        | 'ang'
+        | 'aud'
+        | 'awg'
+        | 'azn'
+        | 'bam'
+        | 'bbd'
+        | 'bdt'
+        | 'bgn'
+        | 'bif'
+        | 'bmd'
+        | 'bnd'
+        | 'bsd'
+        | 'bwp'
+        | 'byn'
+        | 'bzd'
+        | 'brl'
+        | 'cad'
+        | 'cdf'
+        | 'chf'
+        | 'cny'
+        | 'czk'
+        | 'dkk'
+        | 'dop'
+        | 'dzd'
+        | 'egp'
+        | 'etb'
+        | 'eur'
+        | 'fjd'
+        | 'gbp'
+        | 'gel'
+        | 'gip'
+        | 'gmd'
+        | 'gyd'
+        | 'hkd'
+        | 'hrk'
+        | 'htg'
+        | 'idr'
+        | 'ils'
+        | 'inr'
+        | 'isk'
+        | 'jmd'
+        | 'jpy'
+        | 'kes'
+        | 'kgs'
+        | 'khr'
+        | 'kmf'
+        | 'krw'
+        | 'kyd'
+        | 'kzt'
+        | 'lbp'
+        | 'lkr'
+        | 'lrd'
+        | 'lsl'
+        | 'mad'
+        | 'mdl'
+        | 'mga'
+        | 'mkd'
+        | 'mmk'
+        | 'mnt'
+        | 'mop'
+        | 'mro'
+        | 'mvr'
+        | 'mwk'
+        | 'mxn'
+        | 'myr'
+        | 'mzn'
+        | 'nad'
+        | 'ngn'
+        | 'nok'
+        | 'npr'
+        | 'nzd'
+        | 'pgk'
+        | 'php'
+        | 'pkr'
+        | 'pln'
+        | 'qar'
+        | 'ron'
+        | 'rsd'
+        | 'rub'
+        | 'rwf'
+        | 'sar'
+        | 'sbd'
+        | 'scr'
+        | 'sek'
+        | 'sgd'
+        | 'sle'
+        | 'sll'
+        | 'sos'
+        | 'szl'
+        | 'thb'
+        | 'tjs'
+        | 'top'
+        | 'try'
+        | 'ttd'
+        | 'tzs'
+        | 'uah'
+        | 'uzs'
+        | 'vnd'
+        | 'vuv'
+        | 'wst'
+        | 'xaf'
+        | 'xcd'
+        | 'yer'
+        | 'zar'
+        | 'zmw'
+        | 'clp'
+        | 'djf'
+        | 'gnf'
+        | 'ugx'
+        | 'pyg'
+        | 'xof'
+        | 'xpf';
+    }
+  }
+}
+
 /**
  * Response containing task ID for publish operation
  */
@@ -408,54 +1723,67 @@ export namespace PlanRemoveDraftResponse {
 
 export interface PlanCreateParams {
   /**
-   * The unique identifier for the entity
+   * Body param: The unique identifier for the entity
    */
   id: string;
 
   /**
-   * The display name of the package
+   * Body param: The display name of the package
    */
   displayName: string;
 
   /**
-   * The product ID to associate the plan with
+   * Body param: The product ID to associate the plan with
    */
   productId: string;
 
   /**
-   * The unique identifier for the entity in the billing provider
+   * Body param: The unique identifier for the entity in the billing provider
    */
   billingId?: string | null;
 
   /**
-   * Default trial configuration for the plan
+   * Body param: Default trial configuration for the plan
    */
   defaultTrialConfig?: PlanCreateParams.DefaultTrialConfig | null;
 
   /**
-   * The description of the package
+   * Body param: The description of the package
    */
   description?: string | null;
 
   /**
-   * Metadata associated with the entity
+   * Body param: Metadata associated with the entity
    */
   metadata?: { [key: string]: string };
 
   /**
-   * The ID of the parent plan, if applicable
+   * Body param: The ID of the parent plan, if applicable
    */
   parentPlanId?: string | null;
 
   /**
-   * The pricing type of the package
+   * Body param: The pricing type of the package
    */
   pricingType?: 'FREE' | 'PAID' | 'CUSTOM' | null;
 
   /**
-   * The status of the package
+   * Body param: The status of the package
    */
   status?: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 export namespace PlanCreateParams {
@@ -502,43 +1830,74 @@ export namespace PlanCreateParams {
   }
 }
 
+export interface PlanRetrieveParams {
+  /**
+   * Account ID — optional when authenticating with a user JWT (Bearer token); falls
+   * back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Environment ID — required when authenticating with a user JWT (Bearer token) on
+   * environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the
+   * key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
 export interface PlanUpdateParams {
   /**
-   * The unique identifier for the entity in the billing provider
+   * Body param: The unique identifier for the entity in the billing provider
    */
   billingId?: string | null;
 
   /**
-   * Pricing configuration to set on the plan draft
+   * Body param: Pricing configuration to set on the plan draft
    */
   charges?: PlanUpdateParams.Charges;
 
+  /**
+   * Body param
+   */
   compatibleAddonIds?: Array<string> | null;
 
   /**
-   * Default trial configuration for the plan
+   * Body param: Default trial configuration for the plan
    */
   defaultTrialConfig?: PlanUpdateParams.DefaultTrialConfig | null;
 
   /**
-   * The description of the package
+   * Body param: The description of the package
    */
   description?: string | null;
 
   /**
-   * The display name of the package
+   * Body param: The display name of the package
    */
   displayName?: string;
 
   /**
-   * Metadata associated with the entity
+   * Body param: Metadata associated with the entity
    */
   metadata?: { [key: string]: string };
 
   /**
-   * The ID of the parent plan, if applicable
+   * Body param: The ID of the parent plan, if applicable
    */
   parentPlanId?: string | null;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 export namespace PlanUpdateParams {
@@ -1953,19 +3312,33 @@ export namespace PlanUpdateParams {
 
 export interface PlanListParams extends MyCursorIDPageParams {
   /**
-   * Filter by creation date using range operators: gt, gte, lt, lte
+   * Query param: Filter by creation date using range operators: gt, gte, lt, lte
    */
   createdAt?: PlanListParams.CreatedAt;
 
   /**
-   * Filter by product ID
+   * Query param: Filter by product ID
    */
   productId?: string;
 
   /**
-   * Filter by status. Supports comma-separated values for multiple statuses
+   * Query param: Filter by status. Supports comma-separated values for multiple
+   * statuses
    */
   status?: Array<'DRAFT' | 'PUBLISHED' | 'ARCHIVED'>;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 export namespace PlanListParams {
@@ -1995,11 +3368,99 @@ export namespace PlanListParams {
   }
 }
 
+export interface PlanArchiveParams {
+  /**
+   * Account ID — optional when authenticating with a user JWT (Bearer token); falls
+   * back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Environment ID — required when authenticating with a user JWT (Bearer token) on
+   * environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the
+   * key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export interface PlanCreateDraftParams {
+  /**
+   * Account ID — optional when authenticating with a user JWT (Bearer token); falls
+   * back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Environment ID — required when authenticating with a user JWT (Bearer token) on
+   * environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the
+   * key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export interface PlanListChargesParams extends MyCursorIDPageParams {
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export interface PlanListOverageChargesParams extends MyCursorIDPageParams {
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
 export interface PlanPublishParams {
   /**
-   * The migration type of the package
+   * Body param: The migration type of the package
    */
   migrationType: 'NEW_CUSTOMERS' | 'ALL_CUSTOMERS';
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export interface PlanRemoveDraftParams {
+  /**
+   * Account ID — optional when authenticating with a user JWT (Bearer token); falls
+   * back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Environment ID — required when authenticating with a user JWT (Bearer token) on
+   * environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the
+   * key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 Plans.Entitlements = Entitlements;
@@ -2008,13 +3469,23 @@ export declare namespace Plans {
   export {
     type Plan as Plan,
     type PlanListResponse as PlanListResponse,
+    type PlanListChargesResponse as PlanListChargesResponse,
+    type PlanListOverageChargesResponse as PlanListOverageChargesResponse,
     type PlanPublishResponse as PlanPublishResponse,
     type PlanRemoveDraftResponse as PlanRemoveDraftResponse,
     type PlanListResponsesMyCursorIDPage as PlanListResponsesMyCursorIDPage,
+    type PlanListChargesResponsesMyCursorIDPage as PlanListChargesResponsesMyCursorIDPage,
+    type PlanListOverageChargesResponsesMyCursorIDPage as PlanListOverageChargesResponsesMyCursorIDPage,
     type PlanCreateParams as PlanCreateParams,
+    type PlanRetrieveParams as PlanRetrieveParams,
     type PlanUpdateParams as PlanUpdateParams,
     type PlanListParams as PlanListParams,
+    type PlanArchiveParams as PlanArchiveParams,
+    type PlanCreateDraftParams as PlanCreateDraftParams,
+    type PlanListChargesParams as PlanListChargesParams,
+    type PlanListOverageChargesParams as PlanListOverageChargesParams,
     type PlanPublishParams as PlanPublishParams,
+    type PlanRemoveDraftParams as PlanRemoveDraftParams,
   };
 
   export {
@@ -2024,6 +3495,7 @@ export declare namespace Plans {
     type EntitlementListResponse as EntitlementListResponse,
     type EntitlementCreateParams as EntitlementCreateParams,
     type EntitlementUpdateParams as EntitlementUpdateParams,
+    type EntitlementListParams as EntitlementListParams,
     type EntitlementDeleteParams as EntitlementDeleteParams,
   };
 }