@metronome/sdk 2.2.0 → 3.4.1

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);
@@ -494,7 +497,7 @@ export namespace RateCardUpdateParams {
 
 export interface RateCardListParams extends CursorPageParams {
   /**
-   * Body param:
+   * Body param
    */
   body?: unknown;
 }

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
@@ -196,13 +199,6 @@ export namespace RateAddResponse {
      * Only set for TIERED rate_type.
      */
     tiers?: Array<Shared.Tier>;
-
-    /**
-     * Only set for PERCENTAGE rate_type. Defaults to false. If true, rate is computed
-     * using list prices rather than the standard rates for this product on the
-     * contract.
-     */
-    use_list_prices?: boolean;
   }
 }
 
@@ -278,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
@@ -343,13 +339,6 @@ export interface RateAddParams {
    * Only set for TIERED rate_type.
    */
   tiers?: Array<Shared.Tier>;
-
-  /**
-   * Only set for PERCENTAGE rate_type. Defaults to false. If true, rate is computed
-   * using list prices rather than the standard rates for this product on the
-   * contract.
-   */
-  use_list_prices?: boolean;
 }
 
 export interface RateAddManyParams {
@@ -367,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
@@ -432,13 +421,6 @@ export namespace RateAddManyParams {
      * Only set for TIERED rate_type.
      */
     tiers?: Array<Shared.Tier>;
-
-    /**
-     * Only set for PERCENTAGE rate_type. Defaults to false. If true, rate is computed
-     * using list prices rather than the standard rates for this product on the
-     * contract.
-     */
-    use_list_prices?: boolean;
   }
 }
 

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,
@@ -180,7 +183,11 @@ export interface CustomFieldListKeysResponse {
     | 'product'
     | 'rate_card'
     | 'scheduled_charge'
-    | 'subscription';
+    | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge';
 
   key: string;
 }
@@ -206,7 +213,11 @@ export interface CustomFieldAddKeyParams {
     | 'product'
     | 'rate_card'
     | 'scheduled_charge'
-    | 'subscription';
+    | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge';
 
   key: string;
 }
@@ -230,7 +241,11 @@ export interface CustomFieldDeleteValuesParams {
     | 'product'
     | 'rate_card'
     | 'scheduled_charge'
-    | 'subscription';
+    | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge';
 
   entity_id: string;
 
@@ -260,6 +275,10 @@ export interface CustomFieldListKeysParams extends CursorPageWithoutLimitParams
     | 'rate_card'
     | 'scheduled_charge'
     | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge'
   >;
 }
 
@@ -282,7 +301,11 @@ export interface CustomFieldRemoveKeyParams {
     | 'product'
     | 'rate_card'
     | 'scheduled_charge'
-    | 'subscription';
+    | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge';
 
   key: string;
 }
@@ -311,7 +334,11 @@ export interface CustomFieldSetValuesParams {
     | 'product'
     | 'rate_card'
     | 'scheduled_charge'
-    | 'subscription';
+    | 'subscription'
+    | 'package_commit'
+    | 'package_credit'
+    | 'package_subscription'
+    | 'package_scheduled_charge';
 
   entity_id: string;
 }

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)
@@ -161,7 +164,7 @@ export namespace BillingConfigRetrieveResponse {
 
 export interface BillingConfigCreateParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -186,22 +189,22 @@ export interface BillingConfigCreateParams {
   billing_provider_customer_id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   aws_customer_account_id?: string;
 
   /**
-   * Body param:
+   * Body param
    */
   aws_customer_id?: string;
 
   /**
-   * Body param:
+   * Body param
    */
   aws_product_code?: string;
 
   /**
-   * Body param:
+   * Body param
    */
   aws_region?:
     | 'af-south-1'

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,9 +1076,21 @@ 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:
+   * Path param
    */
   customer_id: string;
 
@@ -1021,7 +1108,7 @@ export interface CustomerListBillableMetricsParams extends CursorPageParams {
 
 export interface CustomerListCostsParams extends CursorPageParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -1038,7 +1125,7 @@ export interface CustomerListCostsParams extends CursorPageParams {
 
 export interface CustomerPreviewEventsParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -1146,19 +1233,19 @@ export namespace CustomerSetBillingConfigurationsParams {
 
 export interface CustomerSetIngestAliasesParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   ingest_aliases: Array<string>;
 }
 
 export interface CustomerSetNameParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -1171,7 +1258,7 @@ export interface CustomerSetNameParams {
 
 export interface CustomerUpdateConfigParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -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;
 
@@ -367,6 +370,8 @@ export interface Invoice {
    */
   reseller_royalty?: Invoice.ResellerRoyalty;
 
+  revenue_system_invoices?: Array<Invoice.RevenueSystemInvoice> | null;
+
   /**
    * This field's availability is dependent on your client's configuration.
    */
@@ -498,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;
 
@@ -581,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.
      */
@@ -605,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;
@@ -904,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;
@@ -943,6 +954,21 @@ export namespace Invoice {
       gcp_offer_id?: string;
     }
   }
+
+  export interface RevenueSystemInvoice {
+    revenue_system_external_entity_type: string;
+
+    revenue_system_provider: string;
+
+    sync_status: string;
+
+    /**
+     * The error message from the revenue system, if available.
+     */
+    error_message?: string;
+
+    revenue_system_external_entity_id?: string;
+  }
 }
 
 export interface InvoiceRetrieveResponse {
@@ -959,12 +985,12 @@ export interface InvoiceListBreakdownsResponse extends Invoice {
 
 export interface InvoiceRetrieveParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
   /**
-   * Path param:
+   * Path param
    */
   invoice_id: string;
 
@@ -977,7 +1003,7 @@ export interface InvoiceRetrieveParams {
 
 export interface InvoiceListParams extends CursorPageParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -1018,7 +1044,7 @@ export interface InvoiceListParams extends CursorPageParams {
 
 export interface InvoiceAddChargeParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_id: string;
 
@@ -1035,7 +1061,7 @@ export interface InvoiceAddChargeParams {
   customer_plan_id: string;
 
   /**
-   * Body param:
+   * Body param
    */
   description: string;
 
@@ -1051,14 +1077,14 @@ export interface InvoiceAddChargeParams {
   price: number;
 
   /**
-   * Body param:
+   * Body param
    */
   quantity: number;
 }
 
 export interface InvoiceListBreakdownsParams extends CursorPageParams {
   /**
-   * Path param:
+   * Path param
    */
   customer_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