@metronome/sdk 3.0.0 → 3.4.1

package/src/client.ts

@@ -11,7 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
-import * as qs from './internal/qs';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
@@ -233,8 +233,8 @@ export class Metronome {
     return buildHeaders([{ Authorization: `Bearer ${this.bearerToken}` }]);
   }
 
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return qs.stringify(query, { arrayFormat: 'comma' });
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -266,12 +266,13 @@ export class Metronome {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -455,7 +456,7 @@ export class Metronome {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -492,9 +493,14 @@ export class Metronome {
   getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
     path: string,
     Page: new (...args: any[]) => PageClass,
-    opts?: RequestOptions,
+    opts?: PromiseOrValue<RequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
-    return this.requestAPIList(Page, { method: 'get', path, ...opts });
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
   }
 
   requestAPIList<
@@ -502,7 +508,7 @@ export class Metronome {
     PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
   >(
     Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
-    options: FinalRequestOptions,
+    options: PromiseOrValue<FinalRequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
     const request = this.makeRequest(options, null, undefined);
     return new Pagination.PagePromise<PageClass, Item>(this as any as Metronome, request, Page);
@@ -515,9 +521,10 @@ export class Metronome {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -594,9 +601,9 @@ export class Metronome {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -684,6 +691,12 @@ export class Metronome {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -716,6 +729,14 @@ export class Metronome {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -771,6 +792,7 @@ export declare namespace Metronome {
 
   export { V1 as V1 };
 
+  export type BalanceFilter = API.BalanceFilter;
   export type BaseThresholdCommit = API.BaseThresholdCommit;
   export type BaseUsageFilter = API.BaseUsageFilter;
   export type Commit = API.Commit;

package/src/internal/parse.ts

@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: Metronome, props: APIRespo
     const mediaType = contentType?.split(';')[0]?.trim();
     const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
     if (isJSON) {
+      const contentLength = response.headers.get('content-length');
+      if (contentLength === '0') {
+        // if there is no content we can't do anything
+        return undefined as T;
+      }
+
       const json = await response.json();
       return json as T;
     }

package/src/internal/utils/query.ts

@@ -0,0 +1,7 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as qs from '../qs/stringify';
+
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return qs.stringify(query, { arrayFormat: 'comma' });
+}

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/resources/shared.ts

@@ -3,6 +3,23 @@
 import * as Shared from './shared';
 import { BodyCursorPage } from '../core/pagination';
 
+export interface BalanceFilter {
+  /**
+   * The balance type to filter by.
+   */
+  balance_types?: Array<'PREPAID_COMMIT' | 'POSTPAID_COMMIT' | 'CREDIT'>;
+
+  /**
+   * Custom fields to compute balance across. Must match all custom fields
+   */
+  custom_fields?: { [key: string]: string };
+
+  /**
+   * Specific IDs to compute balance across.
+   */
+  ids?: Array<string>;
+}
+
 export interface BaseThresholdCommit {
   /**
    * The commit product that will be used to generate the line item for commit
@@ -407,10 +424,12 @@ export namespace CommitHierarchyConfiguration {
  * list rate when consuming a credit or commit.
  */
 export interface CommitRate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   /**
-   * Commit rate price. For FLAT rate_type, this must be >=0.
+   * Commit rate price. For FLAT rate_type, this must be >=0. For PERCENTAGE
+   * rate_type, this is a decimal fraction, e.g. use 0.1 for 10%; this must be >=0
+   * and <=1.
    */
   price?: number;
 
@@ -438,8 +457,16 @@ export interface CommitSpecifier {
 }
 
 export interface CommitSpecifierInput {
+  /**
+   * If provided, the specifier will apply to product usage with these set of
+   * presentation group values.
+   */
   presentation_group_values?: { [key: string]: string };
 
+  /**
+   * If provided, the specifier will apply to product usage with these set of pricing
+   * group values.
+   */
   pricing_group_values?: { [key: string]: string };
 
   /**
@@ -481,12 +508,12 @@ export interface Contract {
    */
   customer_billing_provider_configuration?: Contract.CustomerBillingProviderConfiguration;
 
-  prepaid_balance_threshold_configuration?: PrepaidBalanceThresholdConfiguration;
-
   /**
-   * Priority of the contract.
+   * ID of the package this contract was created from, if applicable.
    */
-  priority?: number;
+  package_id?: string;
+
+  prepaid_balance_threshold_configuration?: PrepaidBalanceThresholdConfiguration;
 
   /**
    * Determines which scheduled and commit charges to consolidate onto the Contract's
@@ -1101,7 +1128,7 @@ export namespace ContractV2 {
     }
 
     export interface OverwriteRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
       credit_type?: Shared.CreditTypeData;
 
@@ -1433,8 +1460,8 @@ export namespace ContractV2 {
 
     export interface ParentBehavior {
       /**
-       * Account hierarchy M3 - Indicates the desired behavior of consolidated invoices
-       * generated by the parent in a customer hierarchy
+       * Indicates the desired behavior of consolidated invoices generated by the parent
+       * in a customer hierarchy
        *
        * **CONCATENATE**: Statements on the invoices of child customers will be appended
        * to the consolidated invoice
@@ -1452,15 +1479,15 @@ export namespace ContractV2 {
     parent: ChildHierarchyConfigurationV2.Parent;
 
     /**
-     * Account hierarchy M3 - Indicates which customer should pay for the child's
-     * invoice charges **SELF**: The child pays for its own invoice charges **PARENT**:
-     * The parent pays for the child's invoice charges
+     * Indicates which customer should pay for the child's invoice charges **SELF**:
+     * The child pays for its own invoice charges **PARENT**: The parent pays for the
+     * child's invoice charges
      */
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * Account hierarchy M3 - Indicates the behavior of the child's invoice statements
-     * on the parent's invoices.
+     * Indicates the behavior of the child's invoice statements on the parent's
+     * invoices.
      *
      * **CONSOLIDATE**: Child's invoice statements will be added to parent's
      * consolidated invoices
@@ -2536,8 +2563,8 @@ export namespace HierarchyConfiguration {
 
     export interface ParentBehavior {
       /**
-       * Account hierarchy M3 - Indicates the desired behavior of consolidated invoices
-       * generated by the parent in a customer hierarchy
+       * Indicates the desired behavior of consolidated invoices generated by the parent
+       * in a customer hierarchy
        *
        * **CONCATENATE**: Statements on the invoices of child customers will be appended
        * to the consolidated invoice
@@ -2555,8 +2582,7 @@ export namespace HierarchyConfiguration {
     parent: ChildHierarchyConfiguration.Parent;
 
     /**
-     * Account hierarchy M3 - Indicates which customer should pay for the child's
-     * invoice charges
+     * Indicates which customer should pay for the child's invoice charges
      *
      * **SELF**: The child pays for its own invoice charges
      *
@@ -2565,8 +2591,8 @@ export namespace HierarchyConfiguration {
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * Account hierarchy M3 - Indicates the behavior of the child's invoice statements
-     * on the parent's invoices.
+     * Indicates the behavior of the child's invoice statements on the parent's
+     * invoices.
      *
      * **CONSOLIDATE**: Child's invoice statements will be added to parent's
      * consolidated invoices
@@ -2637,7 +2663,7 @@ export interface Override {
    */
   quantity?: number;
 
-  rate_type?: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type?: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   target?: 'COMMIT_RATE' | 'LIST_RATE';
 
@@ -2688,7 +2714,7 @@ export interface OverrideTier {
 }
 
 export interface OverwriteRate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   credit_type?: CreditTypeData;
 
@@ -2745,7 +2771,7 @@ export interface PaymentGateConfig {
    * not wish Metronome to calculate tax on your behalf. Leaving this field blank
    * will default to NONE.
    */
-  tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'AVALARA' | 'PRECALCULATED';
+  tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
 }
 
 export namespace PaymentGateConfig {
@@ -2807,7 +2833,7 @@ export interface PaymentGateConfigV2 {
    * not wish Metronome to calculate tax on your behalf. Leaving this field blank
    * will default to NONE.
    */
-  tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'AVALARA' | 'PRECALCULATED';
+  tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
 }
 
 export namespace PaymentGateConfigV2 {
@@ -3026,7 +3052,7 @@ export interface ProService {
 }
 
 export interface Rate {
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED' | 'TIERED_PERCENTAGE';
 
   credit_type?: CreditTypeData;
 

package/src/resources/v1/alerts.ts

@@ -5,6 +5,9 @@ import * as Shared from '../shared';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)
+ */
 export class Alerts extends APIResource {
   /**
    * Create a new threshold notification to monitor customer spending, balances, and

package/src/resources/v1/audit-logs.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Security](https://docs.metronome.com/developer-resources/security/) endpoints allow you to retrieve security-related data.
+ */
 export class AuditLogs extends APIResource {
   /**
    * Get a comprehensive audit trail of all operations performed in your Metronome

package/src/resources/v1/billable-metrics.ts

@@ -7,6 +7,9 @@ import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagin
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * [Billable metrics](https://docs.metronome.com/understanding-metronome/how-metronome-works#billable-metrics) in Metronome represent the various consumption components that Metronome meters and aggregates.
+ */
 export class BillableMetrics extends APIResource {
   /**
    * Create billable metrics programmatically with this endpoint—an essential step in

package/src/resources/v1/contracts/contracts.ts

@@ -374,6 +374,79 @@ export class Contracts extends APIResource {
     return this._client.post('/v1/contracts/createHistoricalInvoices', { body, ...options });
   }
 
+  /**
+   * Retrieve the combined current balance across any grouping of credits and commits
+   * for a customer in a single API call.
+   *
+   * - Display real-time available balance to customers in billing dashboards
+   * - Build finance dashboards showing credit utilization across customer segments
+   * - Validate expected vs. actual balance during billing reconciliation
+   *
+   * ### Key response fields:
+   *
+   * - `balance`: The combined net balance available to use at this moment across all
+   *   matching commits and credits
+   * - `credit_type_id`: The credit type (fiat or custom pricing unit) the balance is
+   *   denominated in
+   *
+   * ### Filtering options:
+   *
+   * Balance filters allow you to scope the calculation to specific subsets of
+   * commits and credits. When using multiple filter objects, they are OR'd together
+   * — if a commit or credit matches any filter, it's included in the net balance.
+   * Within a single filter object, all specified conditions are AND'd together.
+   *
+   * - **Balance types**: Include any combination of `PREPAID_COMMIT`,
+   *   `POSTPAID_COMMIT`, and `CREDIT` (e.g., `["PREPAID_COMMIT", "CREDIT"]` to
+   *   exclude postpaid commits). If not specified, all balance types are included.
+   * - **Specific IDs**: Target exact commit or credit IDs for precise balance
+   *   queries
+   * - **Custom fields**: Filter by custom field key-value pairs; when multiple pairs
+   *   are provided, commits must match all of them
+   *
+   * **Example**: To get the balance of all free-trial credits OR all
+   * signup-promotion commits, you'd pass two filter objects — one filtering for
+   * CREDIT with custom field campaign: free-trial, and another filtering for
+   * PREPAID_COMMIT with custom field campaign: signup-promotion.
+   *
+   * ### Usage guidelines:
+   *
+   * - **Draft invoice handling**: Use `invoice_inclusion_mode` to control whether
+   *   pending draft invoice deductions are included (`FINALIZED_AND_DRAFT`, the
+   *   default) or excluded (`FINALIZED`) from the balance calculation
+   * - **Account hierarchies**: When querying a child customer, shared commits from
+   *   parent contracts are not included — query the parent customer directly to see
+   *   shared commit balances
+   * - **Negative balances**: Manual ledger entries can cause negative segment
+   *   balances; these are treated as zero when calculating the net balance
+   * - **Credit types**: If `credit_type_id` is not specified, the balance defaults
+   *   to USD (cents)
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.contracts.getNetBalance({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   credit_type_id: '2714e483-4ff1-48e4-9e25-ac732e8f24f2',
+   *   filters: [
+   *     {
+   *       balance_types: ['CREDIT'],
+   *       custom_fields: { campaign: 'free-trial' },
+   *     },
+   *     {
+   *       balance_types: ['PREPAID_COMMIT', 'POSTPAID_COMMIT'],
+   *       custom_fields: { campaign: 'signup-promotion' },
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  getNetBalance(
+    body: ContractGetNetBalanceParams,
+    options?: RequestOptions,
+  ): APIPromise<ContractGetNetBalanceResponse> {
+    return this._client.post('/v1/contracts/customerBalances/getNetBalance', { body, ...options });
+  }
+
   /**
    * Retrieve a comprehensive view of all available balances (commits and credits)
    * for a customer. This endpoint provides real-time visibility into prepaid funds,
@@ -624,6 +697,26 @@ export interface ContractCreateHistoricalInvoicesResponse {
   data: Array<InvoicesAPI.Invoice>;
 }
 
+export interface ContractGetNetBalanceResponse {
+  data: ContractGetNetBalanceResponse.Data;
+}
+
+export namespace ContractGetNetBalanceResponse {
+  export interface Data {
+    /**
+     * The combined net balance that the customer has access to use at this moment
+     * across all pertinent commits and credits.
+     */
+    balance: number;
+
+    /**
+     * The ID of the credit type (can be fiat or a custom pricing unit) that the
+     * balance is for.
+     */
+    credit_type_id: string;
+  }
+}
+
 export type ContractListBalancesResponse = Shared.Commit | Shared.Credit;
 
 export interface ContractRetrieveRateScheduleResponse {
@@ -763,12 +856,20 @@ export interface ContractCreateParams {
 
   overrides?: Array<ContractCreateParams.Override>;
 
-  prepaid_balance_threshold_configuration?: Shared.PrepaidBalanceThresholdConfiguration;
+  /**
+   * Selects the package linked to the specified alias as of the contract's start
+   * date. Mutually exclusive with package_id.
+   */
+  package_alias?: string;
 
   /**
-   * Priority of the contract.
+   * If provided, provisions a customer on a package instead of creating a
+   * traditional contract. When specified, only customer_id, starting_at, package_id,
+   * and uniqueness_key are allowed.
    */
-  priority?: number;
+  package_id?: string;
+
+  prepaid_balance_threshold_configuration?: Shared.PrepaidBalanceThresholdConfiguration;
 
   /**
    * This field's availability is dependent on your client's configuration.
@@ -1124,7 +1225,7 @@ export namespace ContractCreateParams {
        * not wish Metronome to calculate tax on your behalf. Leaving this field blank
        * will default to NONE.
        */
-      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'AVALARA' | 'PRECALCULATED';
+      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
     }
 
     export namespace PaymentGateConfig {
@@ -1228,6 +1329,11 @@ export namespace ContractCreateParams {
 
     rate_type?: 'COMMIT_RATE' | 'LIST_RATE';
 
+    /**
+     * Fraction of unused segments that will be rolled over. Must be between 0 and 1.
+     */
+    rollover_fraction?: number;
+
     /**
      * List of filters that determine what kind of customer usage draws down a commit
      * or credit. A customer's usage needs to meet the condition of at least one of the
@@ -1399,8 +1505,7 @@ export namespace ContractCreateParams {
     parent_behavior?: HierarchyConfiguration.ParentBehavior;
 
     /**
-     * Account hierarchy M3 - Indicates which customer should pay for the child's
-     * invoice charges
+     * Indicates which customer should pay for the child's invoice charges
      *
      * **SELF**: The child pays for its own invoice charges
      *
@@ -1409,8 +1514,8 @@ export namespace ContractCreateParams {
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * Account hierarchy M3 - Indicates the behavior of the child's invoice statements
-     * on the parent's invoices.
+     * Indicates the behavior of the child's invoice statements on the parent's
+     * invoices.
      *
      * **CONSOLIDATE**: Child's invoice statements will be added to parent's
      * consolidated invoices
@@ -1430,8 +1535,8 @@ export namespace ContractCreateParams {
 
     export interface ParentBehavior {
       /**
-       * Account hierarchy M3 - Indicates the desired behavior of consolidated invoices
-       * generated by the parent in a customer hierarchy
+       * Indicates the desired behavior of consolidated invoices generated by the parent
+       * in a customer hierarchy
        *
        * **CONCATENATE**: Statements on the invoices of child customers will be appended
        * to the consolidated invoice
@@ -1573,7 +1678,7 @@ export namespace ContractCreateParams {
      * Required for OVERWRITE type.
      */
     export interface OverwriteRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
       credit_type_id?: string;
 
@@ -2754,7 +2859,7 @@ export namespace ContractAmendParams {
        * not wish Metronome to calculate tax on your behalf. Leaving this field blank
        * will default to NONE.
        */
-      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'AVALARA' | 'PRECALCULATED';
+      tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
     }
 
     export namespace PaymentGateConfig {
@@ -2858,6 +2963,11 @@ export namespace ContractAmendParams {
 
     rate_type?: 'COMMIT_RATE' | 'LIST_RATE';
 
+    /**
+     * Fraction of unused segments that will be rolled over. Must be between 0 and 1.
+     */
+    rollover_fraction?: number;
+
     /**
      * List of filters that determine what kind of customer usage draws down a commit
      * or credit. A customer's usage needs to meet the condition of at least one of the
@@ -3154,7 +3264,7 @@ export namespace ContractAmendParams {
      * Required for OVERWRITE type.
      */
     export interface OverwriteRate {
-      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+      rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
       credit_type_id?: string;
 
@@ -3483,6 +3593,32 @@ export namespace ContractCreateHistoricalInvoicesParams {
   }
 }
 
+export interface ContractGetNetBalanceParams {
+  /**
+   * The ID of the customer.
+   */
+  customer_id: string;
+
+  /**
+   * The ID of the credit type (can be fiat or a custom pricing unit) to get the
+   * balance for. Defaults to USD (cents) if not specified.
+   */
+  credit_type_id?: string;
+
+  /**
+   * Balance filters are OR'd together, so if a given commit or credit matches any of
+   * the filters, it will be included in the net balance.
+   */
+  filters?: Array<Shared.BalanceFilter>;
+
+  /**
+   * Controls which invoices are considered when calculating the remaining balance.
+   * `FINALIZED` considers only deductions from finalized invoices.
+   * `FINALIZED_AND_DRAFT` also includes deductions from pending draft invoices.
+   */
+  invoice_inclusion_mode?: 'FINALIZED' | 'FINALIZED_AND_DRAFT';
+}
+
 export interface ContractListBalancesParams extends BodyCursorPageParams {
   customer_id: string;
 
@@ -3729,6 +3865,7 @@ export declare namespace Contracts {
     type ContractAmendResponse as ContractAmendResponse,
     type ContractArchiveResponse as ContractArchiveResponse,
     type ContractCreateHistoricalInvoicesResponse as ContractCreateHistoricalInvoicesResponse,
+    type ContractGetNetBalanceResponse as ContractGetNetBalanceResponse,
     type ContractListBalancesResponse as ContractListBalancesResponse,
     type ContractRetrieveRateScheduleResponse as ContractRetrieveRateScheduleResponse,
     type ContractRetrieveSubscriptionQuantityHistoryResponse as ContractRetrieveSubscriptionQuantityHistoryResponse,
@@ -3742,6 +3879,7 @@ export declare namespace Contracts {
     type ContractAmendParams as ContractAmendParams,
     type ContractArchiveParams as ContractArchiveParams,
     type ContractCreateHistoricalInvoicesParams as ContractCreateHistoricalInvoicesParams,
+    type ContractGetNetBalanceParams as ContractGetNetBalanceParams,
     type ContractListBalancesParams as ContractListBalancesParams,
     type ContractRetrieveRateScheduleParams as ContractRetrieveRateScheduleParams,
     type ContractRetrieveSubscriptionQuantityHistoryParams as ContractRetrieveSubscriptionQuantityHistoryParams,

package/src/resources/v1/contracts/index.ts

@@ -8,6 +8,7 @@ export {
   type ContractAmendResponse,
   type ContractArchiveResponse,
   type ContractCreateHistoricalInvoicesResponse,
+  type ContractGetNetBalanceResponse,
   type ContractListBalancesResponse,
   type ContractRetrieveRateScheduleResponse,
   type ContractRetrieveSubscriptionQuantityHistoryResponse,
@@ -20,6 +21,7 @@ export {
   type ContractAmendParams,
   type ContractArchiveParams,
   type ContractCreateHistoricalInvoicesParams,
+  type ContractGetNetBalanceParams,
   type ContractListBalancesParams,
   type ContractRetrieveRateScheduleParams,
   type ContractRetrieveSubscriptionQuantityHistoryParams,

package/src/resources/v1/contracts/named-schedules.ts

@@ -5,6 +5,9 @@ import { APIPromise } from '../../../core/api-promise';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Named schedules are used for storing custom data that can change over time. Named schedules are often used in custom pricing logic.
+ */
 export class NamedSchedules extends APIResource {
   /**
    * Get a named schedule for the given rate card. This endpoint's availability is