@metronome/sdk 2.0.0 → 2.2.0

package/src/resources/shared.ts

@@ -563,7 +563,8 @@ export namespace Contract {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     delivery_method: 'direct_to_billing_provider' | 'aws_sqs' | 'tackle' | 'aws_sns';
 
@@ -822,6 +823,11 @@ export namespace ContractV2 {
      * specifiers to contribute to a commit's or credit's drawdown.
      */
     specifiers?: Array<Shared.CommitSpecifier>;
+
+    /**
+     * Attach a subscription to the recurring commit/credit.
+     */
+    subscription_config?: Shared.RecurringCommitSubscriptionConfig;
   }
 
   export namespace Commit {
@@ -1164,6 +1170,14 @@ export namespace ContractV2 {
 
     contract?: Credit.Contract;
 
+    /**
+     * Timestamp of when the credit was created.
+     *
+     * - Recurring credits: latter of credit service period date and parent credit
+     *   start date
+     */
+    created_at?: string;
+
     /**
      * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
      */
@@ -1214,6 +1228,11 @@ export namespace ContractV2 {
      * specifiers to contribute to a commit's or credit's drawdown.
      */
     specifiers?: Array<Shared.CommitSpecifier>;
+
+    /**
+     * Attach a subscription to the recurring commit/credit.
+     */
+    subscription_config?: Shared.RecurringCommitSubscriptionConfig;
   }
 
   export namespace Credit {
@@ -1327,7 +1346,8 @@ export namespace ContractV2 {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     delivery_method: 'direct_to_billing_provider' | 'aws_sqs' | 'tackle' | 'aws_sns';
   }
@@ -1370,10 +1390,13 @@ export namespace ContractV2 {
 
     export interface ParentBehavior {
       /**
-       * 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 **NONE**: Do not generate
-       * consolidated invoices
+       * Account hierarchy M3 - 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
+       *
+       * **NONE**: Do not generate consolidated invoices
        */
       invoice_consolidation_type?: 'CONCATENATE' | 'NONE';
     }
@@ -1386,15 +1409,21 @@ export namespace ContractV2 {
     parent: ChildHierarchyConfigurationV2.Parent;
 
     /**
-     * Indicates whether the child or parent should pay for the child's invoice charges
+     * 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
      */
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * 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 **SEPARATE**: Child's invoice statements will appear not
-     * appear on parent's consolidated invoices
+     * Account hierarchy M3 - 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
+     *
+     * **SEPARATE**: Child's invoice statements will appear not appear on parent's
+     * consolidated invoices
      */
     usage_statement_behavior?: 'CONSOLIDATE' | 'SEPARATE';
   }
@@ -2431,10 +2460,13 @@ export namespace HierarchyConfiguration {
 
     export interface ParentBehavior {
       /**
-       * 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 **NONE**: Do not generate
-       * consolidated invoices
+       * Account hierarchy M3 - 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
+       *
+       * **NONE**: Do not generate consolidated invoices
        */
       invoice_consolidation_type?: 'CONCATENATE' | 'NONE';
     }
@@ -2447,15 +2479,24 @@ export namespace HierarchyConfiguration {
     parent: ChildHierarchyConfiguration.Parent;
 
     /**
-     * Indicates whether the parent should pay for the child's invoice charges
+     * 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
      */
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * 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 **SEPARATE**: Child's invoice statements will appear not
-     * appear on parent's consolidated invoices
+     * Account hierarchy M3 - 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
+     *
+     * **SEPARATE**: Child's invoice statements will appear not appear on parent's
+     * consolidated invoices
      */
     usage_statement_behavior?: 'CONSOLIDATE' | 'SEPARATE';
   }
@@ -3104,6 +3145,11 @@ export interface Subscription {
    * 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**: 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';
 
@@ -3131,6 +3177,8 @@ export interface Subscription {
   fiat_credit_type_id?: string;
 
   name?: string;
+
+  seat_config?: Subscription.SeatConfig;
 }
 
 export namespace Subscription {
@@ -3192,6 +3240,18 @@ export namespace Subscription {
       name: string;
     }
   }
+
+  export interface SeatConfig {
+    /**
+     * 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;
+  }
 }
 
 export interface Tier {

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

@@ -279,7 +279,7 @@ export class Contracts extends APIResource {
   /**
    * Amendments will be replaced by Contract editing. New clients should implement
    * using the `editContract` endpoint. Read more about the migration to contract
-   * editing [here](https://docs.metronome.com/migrate-amendments-to-edits/) and
+   * editing [here](/guides/implement-metronome/migrate-amendments-to-edits/) and
    * reach out to your Metronome representative for more details. Once contract
    * editing is enabled, access to this endpoint will be removed.
    *
@@ -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.
    */
@@ -1393,15 +1399,24 @@ export namespace ContractCreateParams {
     parent_behavior?: HierarchyConfiguration.ParentBehavior;
 
     /**
-     * Indicates whether the parent should pay for the child's invoice charges
+     * 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
      */
     payer?: 'SELF' | 'PARENT';
 
     /**
-     * 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 **SEPARATE**: Child's invoice statements will appear not
-     * appear on parent's consolidated invoices
+     * Account hierarchy M3 - 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
+     *
+     * **SEPARATE**: Child's invoice statements will appear not appear on parent's
+     * consolidated invoices
      */
     usage_statement_behavior?: 'CONSOLIDATE' | 'SEPARATE';
   }
@@ -1415,10 +1430,13 @@ export namespace ContractCreateParams {
 
     export interface ParentBehavior {
       /**
-       * 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 **NONE**: Do not generate
-       * consolidated invoices
+       * Account hierarchy M3 - 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
+       *
+       * **NONE**: Do not generate consolidated invoices
        */
       invoice_consolidation_type?: 'CONCATENATE' | 'NONE';
     }
@@ -1790,7 +1808,8 @@ export namespace ContractCreateParams {
       subscription_id: string;
 
       /**
-       * If set to POOLED, allocation added per seat is pooled across the account.
+       * 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';
     }
@@ -1951,7 +1970,8 @@ export namespace ContractCreateParams {
       subscription_id: string;
 
       /**
-       * If set to POOLED, allocation added per seat is pooled across the account.
+       * 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';
     }
@@ -2010,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;
 
@@ -2169,9 +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**: 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
@@ -2214,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 {
@@ -2348,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.
@@ -3418,6 +3498,11 @@ export interface ContractListBalancesParams extends BodyCursorPageParams {
    */
   effective_before?: string;
 
+  /**
+   * Exclude balances with zero amounts from the response.
+   */
+  exclude_zero_balances?: boolean;
+
   /**
    * Include archived credits and credits from archived contracts.
    */

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

@@ -15,7 +15,8 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class CreditGrants extends APIResource {
   /**
-   * Create a new credit grant
+   * Create a new credit grant. This is a Plans (deprecated) endpoint. New clients
+   * should implement using Contracts.
    *
    * @example
    * ```ts
@@ -43,7 +44,8 @@ export class CreditGrants extends APIResource {
   }
 
   /**
-   * List credit grants. This list does not included voided grants.
+   * List credit grants. This list does not included voided grants. This is a Plans
+   * (deprecated) endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -79,7 +81,8 @@ export class CreditGrants extends APIResource {
   }
 
   /**
-   * Edit an existing credit grant
+   * Edit an existing credit grant. This is a Plans (deprecated) endpoint. New
+   * clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -97,7 +100,8 @@ export class CreditGrants extends APIResource {
   /**
    * Fetches a list of credit ledger entries. Returns lists of ledgers per customer.
    * Ledger entries are returned in chronological order. Ledger entries associated
-   * with voided credit grants are not included.
+   * with voided credit grants are not included. This is a Plans (deprecated)
+   * endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -129,7 +133,8 @@ export class CreditGrants extends APIResource {
   }
 
   /**
-   * Void a credit grant
+   * Void a credit grant. This is a Plans (deprecated) endpoint. New clients should
+   * implement using Contracts.
    *
    * @example
    * ```ts

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

@@ -241,6 +241,7 @@ export namespace CustomerAlert {
       | 'low_remaining_contract_credit_balance_reached'
       | 'low_remaining_contract_credit_percentage_reached'
       | 'low_remaining_contract_credit_and_commit_balance_reached'
+      | 'low_remaining_seat_balance_reached'
       | 'invoice_total_reached';
 
     /**
@@ -282,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
@@ -314,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;
+    }
   }
 }
 
@@ -343,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 {
@@ -355,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

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class BillingConfig extends APIResource {
   /**
-   * Set the billing configuration for a given customer.
+   * Set the billing configuration for a given customer. This is a Plans (deprecated)
+   * endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -30,7 +31,8 @@ export class BillingConfig extends APIResource {
   }
 
   /**
-   * Fetch the billing configuration for the given customer.
+   * Fetch the billing configuration for the given customer. This is a Plans
+   * (deprecated) endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -54,7 +56,8 @@ export class BillingConfig extends APIResource {
 
   /**
    * Delete the billing configuration for a given customer. Note: this is unsupported
-   * for Azure and AWS Marketplace customers.
+   * for Azure and AWS Marketplace customers. This is a Plans (deprecated) endpoint.
+   * New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -79,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
@@ -140,6 +147,10 @@ export namespace BillingConfigRetrieveResponse {
 
     billing_provider_customer_id?: string;
 
+    /**
+     * The collection method for the customer's invoices. NOTE:
+     * `auto_charge_payment_intent` and `manually_charge_payment_intent` are in beta.
+     */
     stripe_collection_method?:
       | 'charge_automatically'
       | 'send_invoice'
@@ -165,7 +176,8 @@ export interface BillingConfigCreateParams {
     | 'azure_marketplace'
     | 'quickbooks_online'
     | 'workday'
-    | 'gcp_marketplace';
+    | 'gcp_marketplace'
+    | 'metronome';
 
   /**
    * Body param: The customer ID in the billing provider's system. For Azure, this is
@@ -173,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:
    */
@@ -209,7 +231,8 @@ export interface BillingConfigCreateParams {
     | 'us-west-2';
 
   /**
-   * Body param:
+   * Body param: The collection method for the customer's invoices. NOTE:
+   * `auto_charge_payment_intent` and `manually_charge_payment_intent` are in beta.
    */
   stripe_collection_method?:
     | 'charge_automatically'
@@ -232,7 +255,8 @@ export interface BillingConfigRetrieveParams {
     | 'azure_marketplace'
     | 'quickbooks_online'
     | 'workday'
-    | 'gcp_marketplace';
+    | 'gcp_marketplace'
+    | 'metronome';
 }
 
 export interface BillingConfigDeleteParams {
@@ -249,7 +273,8 @@ export interface BillingConfigDeleteParams {
     | 'azure_marketplace'
     | 'quickbooks_online'
     | 'workday'
-    | 'gcp_marketplace';
+    | 'gcp_marketplace'
+    | 'metronome';
 }
 
 export declare namespace BillingConfig {

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

@@ -38,7 +38,8 @@ export class Commits extends APIResource {
    * #### Billing configuration:
    *
    * - invoice_contract_id is required for postpaid commits and for prepaid commits
-   *   with billing (only optional for free prepaid commits)
+   *   with billing (only optional for free prepaid commits) unless do_not_invoice is
+   *   set to true
    * - For postpaid commits: access_schedule and invoice_schedule must have matching
    *   amounts
    * - For postpaid commits: only one schedule item is allowed in both schedules.
@@ -271,7 +272,7 @@ export interface CommitCreateParams {
   /**
    * The contract that this commit will be billed on. This is required for "POSTPAID"
    * commits and for "PREPAID" commits unless there is no invoice schedule above
-   * (i.e., the commit is 'free').
+   * (i.e., the commit is 'free'), or if do_not_invoice is set to true.
    */
   invoice_contract_id?: string;