@metronome/sdk 2.1.0 → 2.2.0

package/src/resources/v1/alerts.ts

@@ -137,7 +137,8 @@ export interface AlertCreateParams {
     | 'low_remaining_contract_credit_balance_reached'
     | 'low_remaining_contract_credit_percentage_reached'
     | 'low_remaining_contract_credit_and_commit_balance_reached'
-    | 'invoice_total_reached';
+    | 'invoice_total_reached'
+    | 'low_remaining_seat_balance_reached';
 
   /**
    * Name of the threshold notification
@@ -209,6 +210,12 @@ export interface AlertCreateParams {
    */
   plan_id?: string;
 
+  /**
+   * Required for `low_remaining_seat_balance_reached` notifications. The alert is
+   * scoped to this seat group key-value pair.
+   */
+  seat_filter?: AlertCreateParams.SeatFilter;
+
   /**
    * Prevents the creation of duplicates. If a request to create a record is made
    * with a previously used uniqueness key, a new record will not be created and the
@@ -231,6 +238,22 @@ export namespace AlertCreateParams {
 
     value?: string;
   }
+
+  /**
+   * Required for `low_remaining_seat_balance_reached` notifications. The alert is
+   * scoped to this seat group key-value pair.
+   */
+  export interface SeatFilter {
+    /**
+     * The seat group key (e.g., "seat_id", "user_id")
+     */
+    seat_group_key: string;
+
+    /**
+     * Optional seat identifier the alert is scoped to.
+     */
+    seat_group_value?: string;
+  }
 }
 
 export interface AlertArchiveParams {

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

@@ -792,6 +792,12 @@ export interface ContractCreateParams {
    */
   reseller_royalties?: Array<ContractCreateParams.ResellerRoyalty>;
 
+  /**
+   * The revenue system configuration associated with a contract. Provide either an
+   * ID or the provider and delivery method.
+   */
+  revenue_system_configuration?: ContractCreateParams.RevenueSystemConfiguration;
+
   /**
    * This field's availability is dependent on your client's configuration.
    */
@@ -1802,9 +1808,8 @@ export namespace ContractCreateParams {
       subscription_id: string;
 
       /**
-       * If set to POOLED, allocation added per seat is pooled across the account. (BETA)
-       * If set to INDIVIDUAL, each seat in the subscription will have its own
-       * allocation.
+       * If set to POOLED, allocation added per seat is pooled across the account. If set
+       * to INDIVIDUAL, each seat in the subscription will have its own allocation.
        */
       allocation?: 'INDIVIDUAL' | 'POOLED';
     }
@@ -1965,9 +1970,8 @@ export namespace ContractCreateParams {
       subscription_id: string;
 
       /**
-       * If set to POOLED, allocation added per seat is pooled across the account. (BETA)
-       * If set to INDIVIDUAL, each seat in the subscription will have its own
-       * allocation.
+       * If set to POOLED, allocation added per seat is pooled across the account. If set
+       * to INDIVIDUAL, each seat in the subscription will have its own allocation.
        */
       allocation?: 'INDIVIDUAL' | 'POOLED';
     }
@@ -2026,6 +2030,31 @@ export namespace ContractCreateParams {
     }
   }
 
+  /**
+   * The revenue system configuration associated with a contract. Provide either an
+   * ID or the provider and delivery method.
+   */
+  export interface RevenueSystemConfiguration {
+    /**
+     * How revenue recognition records should be delivered to the revenue system. Do
+     * not specify if using revenue_system_configuration_id.
+     */
+    delivery_method?: 'direct_to_billing_provider';
+
+    /**
+     * The system that is providing services for revenue recognition. Do not specify if
+     * using revenue_system_configuration_id.
+     */
+    provider?: 'netsuite';
+
+    /**
+     * The Metronome ID of the revenue system configuration. Use when a customer has
+     * multiple configurations with the same provider and delivery method. Otherwise,
+     * specify the provider and delivery_method.
+     */
+    revenue_system_configuration_id?: string;
+  }
+
   export interface ScheduledCharge {
     product_id: string;
 
@@ -2185,14 +2214,16 @@ export namespace ContractCreateParams {
      * QUANTITY_ONLY. **QUANTITY_ONLY**: The subscription quantity is specified
      * directly on the subscription. `initial_quantity` must be provided with this
      * option. Compatible with recurring commits/credits that use POOLED allocation.
-     * **SEAT_BASED**: (BETA) Use when you want to pass specific seat identifiers (e.g.
-     * add user_123) to increment and decrement a subscription quantity, rather than
+     * **SEAT_BASED**: Use when you want to pass specific seat identifiers (e.g. add
+     * user_123) to increment and decrement a subscription quantity, rather than
      * directly providing the quantity. You must use a **SEAT_BASED** subscription to
      * use a linked recurring credit with an allocation per seat. `seat_config` must be
      * provided with this option.
      */
     quantity_management_mode?: 'SEAT_BASED' | 'QUANTITY_ONLY';
 
+    seat_config?: Subscription.SeatConfig;
+
     /**
      * Inclusive start time for the subscription. If not provided, defaults to contract
      * start date
@@ -2235,6 +2266,28 @@ export namespace ContractCreateParams {
        */
       product_id: string;
     }
+
+    export interface SeatConfig {
+      /**
+       * The initial assigned seats on this subscription.
+       */
+      initial_seat_ids: Array<string>;
+
+      /**
+       * The property name, sent on usage events, that identifies the seat ID associated
+       * with the usage event. For example, the property name might be seat_id or
+       * user_id. The property must be set as a group key on billable metrics and a
+       * presentation/pricing group key on contract products. This allows linked
+       * recurring credits with an allocation per seat to be consumed by only one seat's
+       * usage.
+       */
+      seat_group_key: string;
+
+      /**
+       * The initial amount of unassigned seats on this subscription.
+       */
+      initial_unassigned_seats?: number;
+    }
   }
 
   export interface Transition {
@@ -2369,6 +2422,12 @@ export interface ContractAddManualBalanceEntryParams {
    */
   contract_id?: string;
 
+  /**
+   * If using individually configured commits/credits attached to seat managed
+   * subscriptions, the amount to add for each seat. Must sum to total amount.
+   */
+  per_group_amounts?: { [key: string]: number };
+
   /**
    * RFC 3339 timestamp indicating when the manual adjustment takes place. If not
    * provided, it will default to the start of the segment.

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

@@ -283,6 +283,12 @@ export namespace CustomerAlert {
      */
     invoice_types_filter?: Array<string>;
 
+    /**
+     * Only present for low_remaining_seat_balance_reached notifications. The seat
+     * group key or seat group key-value pair the alert is scoped to.
+     */
+    seat_filter?: Alert.SeatFilter;
+
     /**
      * Prevents the creation of duplicates. If a request to create a record is made
      * with a previously used uniqueness key, a new record will not be created and the
@@ -315,6 +321,22 @@ export namespace CustomerAlert {
 
       value?: string;
     }
+
+    /**
+     * Only present for low_remaining_seat_balance_reached notifications. The seat
+     * group key or seat group key-value pair the alert is scoped to.
+     */
+    export interface SeatFilter {
+      /**
+       * The seat group key (e.g., "seat_id", "user_id") that the alert is scoped to.
+       */
+      seat_group_key: string;
+
+      /**
+       * The seat group value that the alert is scoped to.
+       */
+      seat_group_value?: string;
+    }
   }
 }
 
@@ -344,6 +366,12 @@ export interface AlertRetrieveParams {
    * denotes whether to fetch notifications for plans or contracts.
    */
   plans_or_contracts?: 'PLANS' | 'CONTRACTS';
+
+  /**
+   * Only allowed for `low_remaining_seat_balance_reached` notifications. This
+   * filters alerts by the seat group key-value pair.
+   */
+  seat_filter?: AlertRetrieveParams.SeatFilter;
 }
 
 export namespace AlertRetrieveParams {
@@ -356,6 +384,22 @@ export namespace AlertRetrieveParams {
 
     value: string;
   }
+
+  /**
+   * Only allowed for `low_remaining_seat_balance_reached` notifications. This
+   * filters alerts by the seat group key-value pair.
+   */
+  export interface SeatFilter {
+    /**
+     * The seat group key (e.g., "seat_id", "user_id")
+     */
+    seat_group_key: string;
+
+    /**
+     * The specific seat identifier to filter by
+     */
+    seat_group_value: string;
+  }
 }
 
 export interface AlertListParams extends CursorPageWithoutLimitParams {

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

@@ -82,6 +82,10 @@ export interface BillingConfigRetrieveResponse {
 
 export namespace BillingConfigRetrieveResponse {
   export interface Data {
+    aws_customer_account_id?: string;
+
+    aws_customer_id?: string;
+
     /**
      * Contract expiration date for the customer. The expected format is RFC 3339 and
      * can be retrieved from
@@ -181,6 +185,16 @@ export interface BillingConfigCreateParams {
    */
   billing_provider_customer_id: string;
 
+  /**
+   * Body param:
+   */
+  aws_customer_account_id?: string;
+
+  /**
+   * Body param:
+   */
+  aws_customer_id?: string;
+
   /**
    * Body param:
    */

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

@@ -372,7 +372,7 @@ export class Customers extends APIResource {
    *
    * @example
    * ```ts
-   * await client.v1.customers.setBillingConfigurations({
+   * const response = await client.v1.customers.setBillingConfigurations({
    *   data: [
    *     {
    *       customer_id: '4db51251-61de-4bfe-b9ce-495e244f3491',
@@ -398,6 +398,12 @@ export class Customers extends APIResource {
    *       configuration: { ... },
    *       delivery_method: 'direct_to_billing_provider',
    *     },
+   *     {
+   *       customer_id: '4db51251-61de-4bfe-b9ce-495e244f3491',
+   *       billing_provider: 'gcp_marketplace',
+   *       configuration: { ... },
+   *       delivery_method: 'direct_to_billing_provider',
+   *     },
    *   ],
    * });
    * ```
@@ -405,12 +411,8 @@ export class Customers extends APIResource {
   setBillingConfigurations(
     body: CustomerSetBillingConfigurationsParams,
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.post('/v1/setCustomerBillingProviderConfigurations', {
-      body,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<CustomerSetBillingConfigurationsResponse> {
+    return this._client.post('/v1/setCustomerBillingProviderConfigurations', { body, ...options });
   }
 
   /**
@@ -760,6 +762,54 @@ export namespace CustomerRetrieveBillingConfigurationsResponse {
   }
 }
 
+export interface CustomerSetBillingConfigurationsResponse {
+  data: Array<CustomerSetBillingConfigurationsResponse.Data>;
+}
+
+export namespace CustomerSetBillingConfigurationsResponse {
+  export interface Data {
+    /**
+     * ID of the created configuration
+     */
+    id?: string;
+
+    /**
+     * The billing provider set for this configuration.
+     */
+    billing_provider?:
+      | 'aws_marketplace'
+      | 'stripe'
+      | 'netsuite'
+      | 'custom'
+      | 'azure_marketplace'
+      | 'quickbooks_online'
+      | 'workday'
+      | 'gcp_marketplace'
+      | 'metronome';
+
+    /**
+     * Configuration for the billing provider. The structure of this object is specific
+     * to the billing provider and delivery method combination.
+     */
+    configuration?: { [key: string]: unknown };
+
+    /**
+     * ID of the customer this configuration is associated with.
+     */
+    customer_id?: string;
+
+    /**
+     * ID of the delivery method used for this customer configuration.
+     */
+    delivery_method_id?: string;
+
+    /**
+     * The tax provider set for this configuration.
+     */
+    tax_provider?: 'anrok' | 'avalara' | 'stripe';
+  }
+}
+
 export interface CustomerSetNameResponse {
   data: Customer;
 }
@@ -779,6 +829,8 @@ export interface CustomerCreateParams {
 
   customer_billing_provider_configurations?: Array<CustomerCreateParams.CustomerBillingProviderConfiguration>;
 
+  customer_revenue_system_configurations?: Array<CustomerCreateParams.CustomerRevenueSystemConfiguration>;
+
   /**
    * (deprecated, use ingest_aliases instead) an alias that can be used to refer to
    * this customer in usage events
@@ -806,6 +858,10 @@ export namespace CustomerCreateParams {
       | 'gcp_marketplace'
       | 'metronome';
 
+    aws_customer_account_id?: string;
+
+    aws_customer_id?: string;
+
     /**
      * True if the aws_product_code is a SAAS subscription product, false otherwise.
      */
@@ -885,6 +941,32 @@ export namespace CustomerCreateParams {
      */
     tax_provider?: 'anrok' | 'avalara' | 'stripe';
   }
+
+  export interface CustomerRevenueSystemConfiguration {
+    /**
+     * The revenue system provider set for this configuration.
+     */
+    provider: 'netsuite';
+
+    /**
+     * Configuration for the revenue system provider. The structure of this object is
+     * specific to the revenue system provider. For NetSuite, this should contain
+     * `netsuite_customer_id`.
+     */
+    configuration?: { [key: string]: unknown };
+
+    /**
+     * The method to use for delivering invoices to this customer. If not provided, the
+     * `delivery_method_id` must be provided.
+     */
+    delivery_method?: 'direct_to_billing_provider';
+
+    /**
+     * ID of the delivery method to use for this customer. If not provided, the
+     * `delivery_method` must be provided.
+     */
+    delivery_method_id?: string;
+  }
 }
 
 export interface CustomerRetrieveParams {
@@ -1124,6 +1206,7 @@ export declare namespace Customers {
     type CustomerListCostsResponse as CustomerListCostsResponse,
     type CustomerPreviewEventsResponse as CustomerPreviewEventsResponse,
     type CustomerRetrieveBillingConfigurationsResponse as CustomerRetrieveBillingConfigurationsResponse,
+    type CustomerSetBillingConfigurationsResponse as CustomerSetBillingConfigurationsResponse,
     type CustomerSetNameResponse as CustomerSetNameResponse,
     type CustomerDetailsCursorPage as CustomerDetailsCursorPage,
     type CustomerListBillableMetricsResponsesCursorPage as CustomerListBillableMetricsResponsesCursorPage,

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

@@ -43,6 +43,7 @@ export {
   type CustomerListCostsResponse,
   type CustomerPreviewEventsResponse,
   type CustomerRetrieveBillingConfigurationsResponse,
+  type CustomerSetBillingConfigurationsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,

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

@@ -738,10 +738,16 @@ export namespace Invoice {
        */
       billing_provider_error?: string;
 
+      /**
+       * The ID of the payment in the external system, if available.
+       */
+      external_payment_id?: string;
+
       external_status?:
         | 'DRAFT'
         | 'FINALIZED'
         | 'PAID'
+        | 'PARTIALLY_PAID'
         | 'UNCOLLECTIBLE'
         | 'VOID'
         | 'DELETED'
@@ -816,10 +822,16 @@ export namespace Invoice {
      */
     billing_provider_error?: string;
 
+    /**
+     * The ID of the payment in the external system, if available.
+     */
+    external_payment_id?: string;
+
     external_status?:
       | 'DRAFT'
       | 'FINALIZED'
       | 'PAID'
+      | 'PARTIALLY_PAID'
       | 'UNCOLLECTIBLE'
       | 'VOID'
       | 'DELETED'

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

@@ -184,6 +184,8 @@ export namespace PlanListPriceAdjustmentsResponse {
      */
     adjustment_type: 'fixed' | 'quantity' | 'percentage' | 'override';
 
+    quantity?: number;
+
     /**
      * Used in pricing tiers. Indicates at what metric value the price applies.
      */

package/src/resources/v1/index.ts

@@ -92,6 +92,7 @@ export {
   type CustomerListCostsResponse,
   type CustomerPreviewEventsResponse,
   type CustomerRetrieveBillingConfigurationsResponse,
+  type CustomerSetBillingConfigurationsResponse,
   type CustomerSetNameResponse,
   type CustomerCreateParams,
   type CustomerRetrieveParams,

package/src/resources/v1/settings/billing-providers.ts

@@ -107,7 +107,7 @@ export interface BillingProviderCreateParams {
   /**
    * The billing provider set for this configuration.
    */
-  billing_provider: 'aws_marketplace' | 'azure_marketplace';
+  billing_provider: 'aws_marketplace' | 'azure_marketplace' | 'gcp_marketplace';
 
   /**
    * Account-level configuration for the billing provider. The structure of this

package/src/resources/v1/settings/settings.ts

@@ -33,6 +33,7 @@ export class Settings extends APIResource {
    *     delivery_method_ids: [
    *       '9a906ebb-fbc7-42e8-8e29-53bfd2db3aca',
    *     ],
+   *     commit_transactions: true,
    *   });
    * ```
    */
@@ -67,6 +68,12 @@ export interface SettingUpsertAvalaraCredentialsParams {
    * found in the response of the `/listConfiguredBillingProviders` endpoint.
    */
   delivery_method_ids: Array<string>;
+
+  /**
+   * Commit transactions if you want Metronome tax calculations used for reporting
+   * and tax filings.
+   */
+  commit_transactions?: boolean;
 }
 
 Settings.BillingProviders = BillingProviders;

package/src/resources/v1/usage.ts

@@ -388,9 +388,10 @@ export namespace UsageSearchResponse {
       aggregation_key?: string;
 
       /**
-       * Specifies the type of aggregation performed on matching events.
+       * Specifies the type of aggregation performed on matching events. Includes
+       * "custom_sql" for events search endpoint responses.
        */
-      aggregation_type?: 'COUNT' | 'LATEST' | 'MAX' | 'SUM' | 'UNIQUE';
+      aggregation_type?: 'COUNT' | 'LATEST' | 'MAX' | 'SUM' | 'UNIQUE' | 'custom_sql';
 
       /**
        * RFC 3339 timestamp indicating when the billable metric was archived. If not

package/src/resources/v1/v1.ts

@@ -171,6 +171,7 @@ import {
   CustomerRetrieveParams,
   CustomerRetrieveResponse,
   CustomerSetBillingConfigurationsParams,
+  CustomerSetBillingConfigurationsResponse,
   CustomerSetIngestAliasesParams,
   CustomerSetNameParams,
   CustomerSetNameResponse,
@@ -280,6 +281,7 @@ export declare namespace V1 {
     type CustomerListCostsResponse as CustomerListCostsResponse,
     type CustomerPreviewEventsResponse as CustomerPreviewEventsResponse,
     type CustomerRetrieveBillingConfigurationsResponse as CustomerRetrieveBillingConfigurationsResponse,
+    type CustomerSetBillingConfigurationsResponse as CustomerSetBillingConfigurationsResponse,
     type CustomerSetNameResponse as CustomerSetNameResponse,
     type CustomerDetailsCursorPage as CustomerDetailsCursorPage,
     type CustomerListBillableMetricsResponsesCursorPage as CustomerListBillableMetricsResponsesCursorPage,