@metronome/sdk 3.0.0 → 3.4.1

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

@@ -7,6 +7,9 @@ import { APIPromise } from '../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Products are the items that customers purchase.
+ */
 export class Products extends APIResource {
   /**
    * Create a new product object. Products in Metronome represent your company's

package/src/resources/v1/contracts/rate-cards/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 contract. This endpoint's availability is

package/src/resources/v1/contracts/rate-cards/product-orders.ts

@@ -5,6 +5,9 @@ import * as Shared from '../../../shared';
 import { APIPromise } from '../../../../core/api-promise';
 import { RequestOptions } from '../../../../internal/request-options';
 
+/**
+ * Rate cards are used to define default pricing for products.
+ */
 export class ProductOrders extends APIResource {
   /**
    * The ordering of products on a rate card determines the order in which the

package/src/resources/v1/contracts/rate-cards/rate-cards.ts

@@ -32,6 +32,9 @@ import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
 import { RequestOptions } from '../../../../internal/request-options';
 
+/**
+ * Rate cards are used to define default pricing for products.
+ */
 export class RateCards extends APIResource {
   productOrders: ProductOrdersAPI.ProductOrders = new ProductOrdersAPI.ProductOrders(this._client);
   rates: RatesAPI.Rates = new RatesAPI.Rates(this._client);

package/src/resources/v1/contracts/rate-cards/rates.ts

@@ -6,6 +6,9 @@ import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
 import { RequestOptions } from '../../../../internal/request-options';
 
+/**
+ * Rate cards are used to define default pricing for products.
+ */
 export class Rates extends APIResource {
   /**
    * Understand the rate schedule at a given timestamp, optionally filtering the list
@@ -153,7 +156,7 @@ export interface RateAddResponse {
 
 export namespace RateAddResponse {
   export interface Data {
-    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED';
+    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'CUSTOM' | 'TIERED' | 'TIERED_PERCENTAGE';
 
     /**
      * A distinct rate on the rate card. You can choose to use this rate rather than
@@ -271,7 +274,7 @@ export interface RateAddParams {
    */
   rate_card_id: string;
 
-  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+  rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
   /**
    * inclusive effective date
@@ -353,7 +356,7 @@ export namespace RateAddManyParams {
      */
     product_id: string;
 
-    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'CUSTOM';
+    rate_type: 'FLAT' | 'PERCENTAGE' | 'SUBSCRIPTION' | 'TIERED' | 'TIERED_PERCENTAGE' | 'CUSTOM';
 
     /**
      * inclusive effective date

package/src/resources/v1/credit-grants.ts

@@ -13,6 +13,9 @@ import {
 } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Credit grants](https://docs.metronome.com/invoicing/how-billing-works/manage-credits/) adjust a customer balance for prepayments, reimbursements, promotions, and so on. Use these endpoints to create, retrieve, update, and delete credit grants.
+ */
 export class CreditGrants extends APIResource {
   /**
    * Create a new credit grant. This is a Plans (deprecated) endpoint. New clients

package/src/resources/v1/custom-fields.ts

@@ -10,6 +10,9 @@ import {
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Custom fields](https://docs.metronome.com/integrations/custom-fields/) enable adding additional data to Metronome entities. Use these endpoints to create, retrieve, update, and delete custom fields.
+ */
 export class CustomFields extends APIResource {
   /**
    * Creates a new custom field key for a given entity (e.g. billable metric,

package/src/resources/v1/customers/alerts.ts

@@ -11,6 +11,9 @@ import {
 import { buildHeaders } from '../../../internal/headers';
 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 {
   /**
    * Retrieve the real-time evaluation status for a specific threshold

package/src/resources/v1/customers/billing-config.ts

@@ -6,6 +6,9 @@ import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * [Customers](https://docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration.
+ */
 export class BillingConfig extends APIResource {
   /**
    * Set the billing configuration for a given customer. This is a Plans (deprecated)

package/src/resources/v1/customers/commits.ts

@@ -7,6 +7,9 @@ import { APIPromise } from '../../../core/api-promise';
 import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Credits and commits are used to manage customer balances.
+ */
 export class Commits extends APIResource {
   /**
    * Creates customer-level commits that establish spending commitments for customers

package/src/resources/v1/customers/credits.ts

@@ -7,6 +7,9 @@ import { APIPromise } from '../../../core/api-promise';
 import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
 
+/**
+ * Credits and commits are used to manage customer balances.
+ */
 export class Credits extends APIResource {
   /**
    * Creates customer-level credits that provide spending allowances or free credit

package/src/resources/v1/customers/customers.ts

@@ -217,6 +217,57 @@ export class Customers extends APIResource {
     return this._client.post('/v1/customers/archive', { body, ...options });
   }
 
+  /**
+   * Deprecate an existing billing configuration for a customer to handle churn or
+   * billing and collection preference changes. Archiving a billing configuration
+   * takes effect immediately. If there are active contracts using the configuration,
+   * Metronome will archive the configuration on the contract and immediately stop
+   * metering to downstream systems.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Remove billing provider customer data and configurations when no longer needed
+   * - Clean up test or deprecated billing provider configurations
+   * - Free up uniqueness keys for reuse with new billing provider configurations
+   * - Disable threshold recharge configurations associated with archived billing
+   *   providers
+   *
+   * ### Key response fields:
+   *
+   * A successful response returns:
+   *
+   * - `success`: Boolean indicating the operation completed successfully
+   * - `error`: Null on success, error message on failure
+   *
+   * ### Usage guidelines:
+   *
+   * - Archiving a contract configuration during a grace period will result in the
+   *   invoice not being sent to the customer
+   * - Automatically disables both spend-based and credit-based threshold recharge
+   *   configurations for contracts using the archived billing provider
+   * - You can archive multiple configurations for a single customer in a single
+   *   request, but any validation failures for an individual configuration will
+   *   prevent the entire operation from succeeding
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.archiveBillingConfigurations({
+   *     customer_billing_provider_configuration_ids: [
+   *       '4db51251-61de-4bfe-b9ce-495e244f3491',
+   *       '4db51251-61de-4bfe-b9ce-495e244f3491',
+   *     ],
+   *     customer_id: '20a060d1-aa80-41d4-8bb2-4f3091b93903',
+   *   });
+   * ```
+   */
+  archiveBillingConfigurations(
+    body: CustomerArchiveBillingConfigurationsParams,
+    options?: RequestOptions,
+  ): APIPromise<CustomerArchiveBillingConfigurationsResponse> {
+    return this._client.post('/v1/archiveCustomerBillingProviderConfigurations', { body, ...options });
+  }
+
   /**
    * Get all billable metrics available for a specific customer. Supports pagination
    * and filtering by current plan status or archived metrics. Use this endpoint to
@@ -404,6 +455,12 @@ export class Customers extends APIResource {
    *       configuration: { ... },
    *       delivery_method: 'direct_to_billing_provider',
    *     },
+   *     {
+   *       customer_id: '4db51251-61de-4bfe-b9ce-495e244f3491',
+   *       billing_provider: 'netsuite',
+   *       configuration: { ... },
+   *       delivery_method: 'direct_to_billing_provider',
+   *     },
    *   ],
    * });
    * ```
@@ -602,6 +659,24 @@ export interface CustomerArchiveResponse {
   data: Shared.ID;
 }
 
+export interface CustomerArchiveBillingConfigurationsResponse {
+  data: CustomerArchiveBillingConfigurationsResponse.Data;
+}
+
+export namespace CustomerArchiveBillingConfigurationsResponse {
+  export interface Data {
+    /**
+     * Array of billing provider configuration IDs to archive
+     */
+    customer_billing_provider_configuration_ids: Array<string>;
+
+    /**
+     * The customer ID the billing provider configurations belong to
+     */
+    customer_id: string;
+  }
+}
+
 export interface CustomerListBillableMetricsResponse {
   id: string;
 
@@ -1001,6 +1076,18 @@ export interface CustomerArchiveParams {
   id: string;
 }
 
+export interface CustomerArchiveBillingConfigurationsParams {
+  /**
+   * Array of billing provider configuration IDs to archive
+   */
+  customer_billing_provider_configuration_ids: Array<string>;
+
+  /**
+   * The customer ID the billing provider configurations belong to
+   */
+  customer_id: string;
+}
+
 export interface CustomerListBillableMetricsParams extends CursorPageParams {
   /**
    * Path param
@@ -1202,6 +1289,7 @@ export declare namespace Customers {
     type CustomerCreateResponse as CustomerCreateResponse,
     type CustomerRetrieveResponse as CustomerRetrieveResponse,
     type CustomerArchiveResponse as CustomerArchiveResponse,
+    type CustomerArchiveBillingConfigurationsResponse as CustomerArchiveBillingConfigurationsResponse,
     type CustomerListBillableMetricsResponse as CustomerListBillableMetricsResponse,
     type CustomerListCostsResponse as CustomerListCostsResponse,
     type CustomerPreviewEventsResponse as CustomerPreviewEventsResponse,
@@ -1215,6 +1303,7 @@ export declare namespace Customers {
     type CustomerRetrieveParams as CustomerRetrieveParams,
     type CustomerListParams as CustomerListParams,
     type CustomerArchiveParams as CustomerArchiveParams,
+    type CustomerArchiveBillingConfigurationsParams as CustomerArchiveBillingConfigurationsParams,
     type CustomerListBillableMetricsParams as CustomerListBillableMetricsParams,
     type CustomerListCostsParams as CustomerListCostsParams,
     type CustomerPreviewEventsParams as CustomerPreviewEventsParams,

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

@@ -39,6 +39,7 @@ export {
   type CustomerCreateResponse,
   type CustomerRetrieveResponse,
   type CustomerArchiveResponse,
+  type CustomerArchiveBillingConfigurationsResponse,
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
   type CustomerPreviewEventsResponse,
@@ -49,6 +50,7 @@ export {
   type CustomerRetrieveParams,
   type CustomerListParams,
   type CustomerArchiveParams,
+  type CustomerArchiveBillingConfigurationsParams,
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
   type CustomerPreviewEventsParams,

package/src/resources/v1/customers/invoices.ts

@@ -8,6 +8,9 @@ import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * [Invoices](https://docs.metronome.com/invoicing/) reflect how much a customer spent during a period, which is the basis for billing. Metronome automatically generates invoices based upon your pricing, packaging, and usage events. Use these endpoints to retrieve invoices.
+ */
 export class Invoices extends APIResource {
   /**
    * Retrieve detailed information for a specific invoice by its unique identifier.
@@ -299,8 +302,8 @@ export interface Invoice {
   billable_status?: unknown;
 
   /**
-   * Account hierarchy M3 - Required on invoices with type USAGE_CONSOLIDATED. List
-   * of constituent invoices that were consolidated to create this invoice.
+   * Required on invoices with type USAGE_CONSOLIDATED. List of constituent invoices
+   * that were consolidated to create this invoice.
    */
   constituent_invoices?: Array<Invoice.ConstituentInvoice>;
 
@@ -348,8 +351,8 @@ export interface Invoice {
   netsuite_sales_order_id?: string;
 
   /**
-   * Account hierarchy M3 - Required for account hierarchy usage invoices. An object
-   * containing the contract and customer UUIDs that pay for this invoice.
+   * Required for account hierarchy usage invoices. An object containing the contract
+   * and customer UUIDs that pay for this invoice.
    */
   payer?: Invoice.Payer;
 
@@ -500,9 +503,9 @@ export namespace Invoice {
     netsuite_item_id?: string;
 
     /**
-     * Account hierarchy M3 - Present on line items from invoices with type
-     * USAGE_CONSOLIDATED. Indicates the original customer, contract, invoice and line
-     * item from which this line item was copied.
+     * Present on line items from invoices with type USAGE_CONSOLIDATED. Indicates the
+     * original customer, contract, invoice and line item from which this line item was
+     * copied.
      */
     origin?: LineItem.Origin;
 
@@ -583,6 +586,12 @@ export namespace Invoice {
      */
     subscription_custom_fields?: { [key: string]: string };
 
+    /**
+     * ID of the subscription that this line item is associated with. Only present on
+     * line items with product of `SUBSCRIPTION` type.
+     */
+    subscription_id?: string;
+
     /**
      * Populated if the line item has a tiered price.
      */
@@ -607,9 +616,9 @@ export namespace Invoice {
     }
 
     /**
-     * Account hierarchy M3 - Present on line items from invoices with type
-     * USAGE_CONSOLIDATED. Indicates the original customer, contract, invoice and line
-     * item from which this line item was copied.
+     * Present on line items from invoices with type USAGE_CONSOLIDATED. Indicates the
+     * original customer, contract, invoice and line item from which this line item was
+     * copied.
      */
     export interface Origin {
       contract_id: string;
@@ -906,8 +915,8 @@ export namespace Invoice {
   }
 
   /**
-   * Account hierarchy M3 - Required for account hierarchy usage invoices. An object
-   * containing the contract and customer UUIDs that pay for this invoice.
+   * Required for account hierarchy usage invoices. An object containing the contract
+   * and customer UUIDs that pay for this invoice.
    */
   export interface Payer {
     contract_id: string;

package/src/resources/v1/customers/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 customer. This endpoint's availability is

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

@@ -7,6 +7,9 @@ import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pa
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
+/**
+ * [Plans](https://docs.metronome.com/pricing-and-packaging/create-plans/) determine the base pricing for a customer. Use these endpoints to add a plan to a customer, end a customer plan, retrieve plans, and retrieve plan details. Create plans in the [Metronome app](https://app.metronome.com/plans).
+ */
 export class Plans extends APIResource {
   /**
    * List the given customer's plans in reverse-chronological order. This is a Plans

package/src/resources/v1/dashboards.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Customers](https://docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration.
+ */
 export class Dashboards extends APIResource {
   /**
    * Generate secure, embeddable dashboard URLs that allow you to seamlessly

package/src/resources/v1/index.ts

@@ -33,6 +33,7 @@ export {
   type ContractAmendResponse,
   type ContractArchiveResponse,
   type ContractCreateHistoricalInvoicesResponse,
+  type ContractGetNetBalanceResponse,
   type ContractListBalancesResponse,
   type ContractRetrieveRateScheduleResponse,
   type ContractRetrieveSubscriptionQuantityHistoryResponse,
@@ -45,6 +46,7 @@ export {
   type ContractAmendParams,
   type ContractArchiveParams,
   type ContractCreateHistoricalInvoicesParams,
+  type ContractGetNetBalanceParams,
   type ContractListBalancesParams,
   type ContractRetrieveRateScheduleParams,
   type ContractRetrieveSubscriptionQuantityHistoryParams,
@@ -88,6 +90,7 @@ export {
   type CustomerCreateResponse,
   type CustomerRetrieveResponse,
   type CustomerArchiveResponse,
+  type CustomerArchiveBillingConfigurationsResponse,
   type CustomerListBillableMetricsResponse,
   type CustomerListCostsResponse,
   type CustomerPreviewEventsResponse,
@@ -98,6 +101,7 @@ export {
   type CustomerRetrieveParams,
   type CustomerListParams,
   type CustomerArchiveParams,
+  type CustomerArchiveBillingConfigurationsParams,
   type CustomerListBillableMetricsParams,
   type CustomerListCostsParams,
   type CustomerPreviewEventsParams,
@@ -122,6 +126,21 @@ export {
   type InvoiceRegenerateParams,
   type InvoiceVoidParams,
 } from './invoices';
+export {
+  Packages,
+  type PackageCreateResponse,
+  type PackageRetrieveResponse,
+  type PackageListResponse,
+  type PackageArchiveResponse,
+  type PackageListContractsOnPackageResponse,
+  type PackageCreateParams,
+  type PackageRetrieveParams,
+  type PackageListParams,
+  type PackageArchiveParams,
+  type PackageListContractsOnPackageParams,
+  type PackageListResponsesCursorPage,
+  type PackageListContractsOnPackageResponsesCursorPage,
+} from './packages';
 export {
   Payments,
   type Payment,

package/src/resources/v1/invoices.ts

@@ -4,6 +4,9 @@ import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
+/**
+ * [Invoices](https://docs.metronome.com/invoicing/) reflect how much a customer spent during a period, which is the basis for billing. Metronome automatically generates invoices based upon your pricing, packaging, and usage events. Use these endpoints to retrieve invoices.
+ */
 export class Invoices extends APIResource {
   /**
    * This endpoint regenerates a voided invoice and recalculates the invoice based on