@metronome/sdk 2.0.0 → 2.1.0

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

@@ -248,7 +248,8 @@ export class Customers extends APIResource {
   /**
    * Fetch daily pending costs for the specified customer, broken down by credit type
    * and line items. Note: this is not supported for customers whose plan includes a
-   * UNIQUE-type billable metric.
+   * UNIQUE-type billable metric. This is a Plans (deprecated) endpoint. New clients
+   * should implement using Contracts.
    *
    * @example
    * ```ts
@@ -280,7 +281,8 @@ export class Customers extends APIResource {
    * Preview how a set of events will affect a customer's invoices. Generates draft
    * invoices for a customer using their current contract configuration and the
    * provided events. This is useful for testing how new events will affect the
-   * customer's invoices before they are actually processed.
+   * customer's invoices before they are actually processed. Customers on contracts
+   * with SQL billable metrics are not supported.
    *
    * @example
    * ```ts
@@ -293,6 +295,7 @@ export class Customers extends APIResource {
    *       properties: { cpu_hours: 100, memory_gb_hours: 200 },
    *     },
    *   ],
+   *   mode: 'replace',
    * });
    * ```
    */
@@ -728,7 +731,8 @@ export namespace CustomerRetrieveBillingConfigurationsResponse {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     /**
      * Configuration for the billing provider. The structure of this object is specific
@@ -799,7 +803,8 @@ export namespace CustomerCreateParams {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     /**
      * True if the aws_product_code is a SAAS subscription product, false otherwise.
@@ -835,6 +840,10 @@ export namespace CustomerCreateParams {
       | 'us-west-1'
       | 'us-west-2';
 
+    /**
+     * 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'
@@ -952,20 +961,21 @@ export interface CustomerPreviewEventsParams {
   customer_id: string;
 
   /**
-   * Body param:
+   * Body param: Array of usage events to include in the preview calculation. Must
+   * contain at least one event in `merge` mode.
    */
   events: Array<CustomerPreviewEventsParams.Event>;
 
   /**
-   * Body param: If set to "replace", the preview will be generated as if those were
-   * the only events for the specified customer. If set to "merge", the events will
-   * be merged with any existing events for the specified customer. Defaults to
-   * "replace".
+   * Body param: Controls how the provided events are combined with existing usage
+   * data. Use `replace` to calculate the preview as if these are the only events for
+   * the customer, ignoring all historical usage. Use `merge` to combine these events
+   * with the customer's existing usage. Defaults to `replace`.
    */
   mode?: 'replace' | 'merge';
 
   /**
-   * Body param: If set, all zero quantity line items will be filtered out of the
+   * Body param: When `true`, line items with zero quantity are excluded from the
    * response.
    */
   skip_zero_qty_line_items?: boolean;
@@ -1014,7 +1024,8 @@ export namespace CustomerSetBillingConfigurationsParams {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     customer_id: string;
 

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

@@ -133,7 +133,8 @@ export class Invoices extends APIResource {
   }
 
   /**
-   * Add a one time charge to the specified invoice
+   * Add a one time charge to the specified invoice. This is a Plans (deprecated)
+   * endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -297,6 +298,12 @@ 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.
+   */
+  constituent_invoices?: Array<Invoice.ConstituentInvoice>;
+
   /**
    * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
    */
@@ -340,6 +347,12 @@ 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.
+   */
+  payer?: Invoice.Payer;
+
   /**
    * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
    */
@@ -484,6 +497,13 @@ 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.
+     */
+    origin?: LineItem.Origin;
+
     /**
      * Only present for line items paying for a postpaid commit true-up.
      */
@@ -584,6 +604,21 @@ export namespace Invoice {
       type: 'PREPAID' | 'POSTPAID' | 'CREDIT';
     }
 
+    /**
+     * 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.
+     */
+    export interface Origin {
+      contract_id: string;
+
+      customer_id: string;
+
+      invoice_id: string;
+
+      line_item_id: string;
+    }
+
     /**
      * Only present for line items paying for a postpaid commit true-up.
      */
@@ -667,6 +702,14 @@ export namespace Invoice {
     }
   }
 
+  export interface ConstituentInvoice {
+    contract_id: string;
+
+    customer_id: string;
+
+    invoice_id: string;
+  }
+
   export interface CorrectionRecord {
     corrected_invoice_id: string;
 
@@ -687,7 +730,13 @@ export namespace Invoice {
         | 'azure_marketplace'
         | 'quickbooks_online'
         | 'workday'
-        | 'gcp_marketplace';
+        | 'gcp_marketplace'
+        | 'metronome';
+
+      /**
+       * Error message from the billing provider, if available.
+       */
+      billing_provider_error?: string;
 
       external_status?:
         | 'DRAFT'
@@ -759,7 +808,13 @@ export namespace Invoice {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
+
+    /**
+     * Error message from the billing provider, if available.
+     */
+    billing_provider_error?: string;
 
     external_status?:
       | 'DRAFT'
@@ -836,6 +891,16 @@ export namespace Invoice {
     credit_grant_id?: string;
   }
 
+  /**
+   * Account hierarchy M3 - 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;
+
+    customer_id: string;
+  }
+
   /**
    * Only present for contract invoices with reseller royalties.
    */

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

@@ -9,7 +9,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Plans extends APIResource {
   /**
-   * List the given customer's plans in reverse-chronological order.
+   * List the given customer's plans in reverse-chronological order. This is a Plans
+   * (deprecated) endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -35,7 +36,8 @@ export class Plans extends APIResource {
   /**
    * Associate an existing customer with a plan for a specified date range. See the
    * [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments)
-   * for details on the price adjustments.
+   * for details on the price adjustments. This is a Plans (deprecated) endpoint. New
+   * clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -53,7 +55,8 @@ export class Plans extends APIResource {
   }
 
   /**
-   * Change the end date of a customer's plan.
+   * Change the end date of a customer's plan. This is a Plans (deprecated) endpoint.
+   * New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -75,7 +78,8 @@ export class Plans extends APIResource {
   /**
    * Lists a customer plans adjustments. See the
    * [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments)
-   * for details.
+   * for details. This is a Plans (deprecated) endpoint. New clients should implement
+   * using Contracts.
    *
    * @example
    * ```ts

package/src/resources/v1/index.ts

@@ -154,6 +154,11 @@ export {
   type PricingUnitListResponsesCursorPage,
 } from './pricing-units';
 export { Services, type ServiceListResponse } from './services';
+export {
+  Settings,
+  type SettingUpsertAvalaraCredentialsResponse,
+  type SettingUpsertAvalaraCredentialsParams,
+} from './settings/index';
 export {
   Usage,
   type UsageListResponse,

package/src/resources/v1/payments.ts

@@ -112,6 +112,8 @@ export namespace Payment {
       payment_intent_id: string;
 
       error?: Stripe.Error;
+
+      payment_method_id?: string;
     }
 
     export namespace Stripe {

package/src/resources/v1/plans.ts

@@ -10,7 +10,8 @@ import { path } from '../../internal/utils/path';
 
 export class Plans extends APIResource {
   /**
-   * List all available plans.
+   * List all available plans. This is a Plans (deprecated) endpoint. New clients
+   * should implement using Contracts.
    *
    * @example
    * ```ts
@@ -28,7 +29,8 @@ export class Plans extends APIResource {
   }
 
   /**
-   * Fetch high level details of a specific plan.
+   * Fetch high level details of a specific plan. This is a Plans (deprecated)
+   * endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -43,7 +45,8 @@ export class Plans extends APIResource {
   }
 
   /**
-   * Fetches a list of charges of a specific plan.
+   * Fetches a list of charges of a specific plan. This is a Plans (deprecated)
+   * endpoint. New clients should implement using Contracts.
    *
    * @example
    * ```ts
@@ -69,7 +72,8 @@ export class Plans extends APIResource {
 
   /**
    * Fetches a list of customers on a specific plan (by default, only currently
-   * active plans are included)
+   * active plans are included). This is a Plans (deprecated) endpoint. New clients
+   * should implement using Contracts.
    *
    * @example
    * ```ts

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

@@ -0,0 +1,139 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class BillingProviders extends APIResource {
+  /**
+   * Set up account-level configuration for a billing provider. Once configured,
+   * individual contracts across customers can be mapped to this configuration using
+   * the returned delivery_method_id.
+   *
+   * @example
+   * ```ts
+   * const billingProvider =
+   *   await client.v1.settings.billingProviders.create({
+   *     billing_provider: 'aws_marketplace',
+   *     configuration: {
+   *       aws_external_id:
+   *         '47b4f6b7-e297-42e8-b175-331d933b402c',
+   *       aws_iam_role_arn: 'arn:aws:iam::test',
+   *     },
+   *     delivery_method: 'direct_to_billing_provider',
+   *   });
+   * ```
+   */
+  create(
+    body: BillingProviderCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<BillingProviderCreateResponse> {
+    return this._client.post('/v1/setUpBillingProvider', { body, ...options });
+  }
+
+  /**
+   * Lists all configured billing providers and their delivery method configurations
+   * for your account. Returns provider details, delivery method IDs, and
+   * configuration settings needed for mapping individual customer contracts to
+   * billing integrations.
+   *
+   * @example
+   * ```ts
+   * const billingProviders =
+   *   await client.v1.settings.billingProviders.list({
+   *     next_page: 'af26878a-de62-4a0d-9b77-3936f7c2b6d6',
+   *   });
+   * ```
+   */
+  list(
+    body: BillingProviderListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BillingProviderListResponse> {
+    return this._client.post('/v1/listConfiguredBillingProviders', { body, ...options });
+  }
+}
+
+export interface BillingProviderCreateResponse {
+  data: BillingProviderCreateResponse.Data;
+}
+
+export namespace BillingProviderCreateResponse {
+  export interface Data {
+    delivery_method_id: string;
+  }
+}
+
+export interface BillingProviderListResponse {
+  data: Array<BillingProviderListResponse.Data>;
+
+  next_page?: string | null;
+}
+
+export namespace BillingProviderListResponse {
+  export interface Data {
+    /**
+     * The billing provider set for this configuration.
+     */
+    billing_provider:
+      | 'aws_marketplace'
+      | 'stripe'
+      | 'netsuite'
+      | 'custom'
+      | 'azure_marketplace'
+      | 'quickbooks_online'
+      | 'workday'
+      | 'gcp_marketplace'
+      | 'metronome';
+
+    /**
+     * The method to use for delivering invoices to this customer.
+     */
+    delivery_method: 'direct_to_billing_provider' | 'aws_sqs' | 'tackle' | 'aws_sns';
+
+    /**
+     * Configuration for the delivery method. The structure of this object is specific
+     * to the delivery method. Some configuration may be omitted for security reasons.
+     */
+    delivery_method_configuration: { [key: string]: unknown };
+
+    /**
+     * ID of the delivery method to use for this customer.
+     */
+    delivery_method_id: string;
+  }
+}
+
+export interface BillingProviderCreateParams {
+  /**
+   * The billing provider set for this configuration.
+   */
+  billing_provider: 'aws_marketplace' | 'azure_marketplace';
+
+  /**
+   * Account-level configuration for the billing provider. The structure of this
+   * object is specific to the billing provider and delivery provider combination.
+   * See examples below.
+   */
+  configuration: { [key: string]: unknown };
+
+  /**
+   * The method to use for delivering invoices for this configuration.
+   */
+  delivery_method: 'direct_to_billing_provider' | 'aws_sqs' | 'aws_sns';
+}
+
+export interface BillingProviderListParams {
+  /**
+   * The cursor to the next page of results
+   */
+  next_page?: string | null;
+}
+
+export declare namespace BillingProviders {
+  export {
+    type BillingProviderCreateResponse as BillingProviderCreateResponse,
+    type BillingProviderListResponse as BillingProviderListResponse,
+    type BillingProviderCreateParams as BillingProviderCreateParams,
+    type BillingProviderListParams as BillingProviderListParams,
+  };
+}

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

@@ -0,0 +1,14 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  BillingProviders,
+  type BillingProviderCreateResponse,
+  type BillingProviderListResponse,
+  type BillingProviderCreateParams,
+  type BillingProviderListParams,
+} from './billing-providers';
+export {
+  Settings,
+  type SettingUpsertAvalaraCredentialsResponse,
+  type SettingUpsertAvalaraCredentialsParams,
+} from './settings';

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

@@ -0,0 +1,87 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as BillingProvidersAPI from './billing-providers';
+import {
+  BillingProviderCreateParams,
+  BillingProviderCreateResponse,
+  BillingProviderListParams,
+  BillingProviderListResponse,
+  BillingProviders,
+} from './billing-providers';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Settings extends APIResource {
+  billingProviders: BillingProvidersAPI.BillingProviders = new BillingProvidersAPI.BillingProviders(
+    this._client,
+  );
+
+  /**
+   * Set the Avalara credentials for some specified `delivery_method_ids`, which can
+   * be found in the `/listConfiguredBillingProviders` response. This maps the
+   * Avalara credentials to the appropriate billing entity. These credentials are
+   * only used for PLG Invoicing today.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.settings.upsertAvalaraCredentials({
+   *     avalara_environment: 'PRODUCTION',
+   *     avalara_password: 'my_password_123',
+   *     avalara_username: 'test@metronome.com',
+   *     delivery_method_ids: [
+   *       '9a906ebb-fbc7-42e8-8e29-53bfd2db3aca',
+   *     ],
+   *   });
+   * ```
+   */
+  upsertAvalaraCredentials(
+    body: SettingUpsertAvalaraCredentialsParams,
+    options?: RequestOptions,
+  ): APIPromise<SettingUpsertAvalaraCredentialsResponse> {
+    return this._client.post('/v1/upsertAvalaraCredentials', { body, ...options });
+  }
+}
+
+export interface SettingUpsertAvalaraCredentialsResponse {}
+
+export interface SettingUpsertAvalaraCredentialsParams {
+  /**
+   * The Avalara environment to use (SANDBOX or PRODUCTION).
+   */
+  avalara_environment: 'PRODUCTION' | 'SANDBOX';
+
+  /**
+   * The password for the Avalara account.
+   */
+  avalara_password: string;
+
+  /**
+   * The username for the Avalara account.
+   */
+  avalara_username: string;
+
+  /**
+   * The delivery method IDs of the billing provider configurations to update, can be
+   * found in the response of the `/listConfiguredBillingProviders` endpoint.
+   */
+  delivery_method_ids: Array<string>;
+}
+
+Settings.BillingProviders = BillingProviders;
+
+export declare namespace Settings {
+  export {
+    type SettingUpsertAvalaraCredentialsResponse as SettingUpsertAvalaraCredentialsResponse,
+    type SettingUpsertAvalaraCredentialsParams as SettingUpsertAvalaraCredentialsParams,
+  };
+
+  export {
+    BillingProviders as BillingProviders,
+    type BillingProviderCreateResponse as BillingProviderCreateResponse,
+    type BillingProviderListResponse as BillingProviderListResponse,
+    type BillingProviderCreateParams as BillingProviderCreateParams,
+    type BillingProviderListParams as BillingProviderListParams,
+  };
+}

package/src/resources/v1/settings.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './settings/index';

package/src/resources/v1/v1.ts

@@ -177,6 +177,12 @@ import {
   CustomerUpdateConfigParams,
   Customers,
 } from './customers/customers';
+import * as SettingsAPI from './settings/settings';
+import {
+  SettingUpsertAvalaraCredentialsParams,
+  SettingUpsertAvalaraCredentialsResponse,
+  Settings,
+} from './settings/settings';
 
 export class V1 extends APIResource {
   alerts: AlertsAPI.Alerts = new AlertsAPI.Alerts(this._client);
@@ -193,6 +199,7 @@ export class V1 extends APIResource {
   invoices: InvoicesAPI.Invoices = new InvoicesAPI.Invoices(this._client);
   contracts: ContractsAPI.Contracts = new ContractsAPI.Contracts(this._client);
   payments: PaymentsAPI.Payments = new PaymentsAPI.Payments(this._client);
+  settings: SettingsAPI.Settings = new SettingsAPI.Settings(this._client);
 }
 
 V1.Alerts = Alerts;
@@ -209,6 +216,7 @@ V1.Services = Services;
 V1.Invoices = Invoices;
 V1.Contracts = Contracts;
 V1.Payments = Payments;
+V1.Settings = Settings;
 
 export declare namespace V1 {
   export {
@@ -390,4 +398,10 @@ export declare namespace V1 {
     type PaymentAttemptParams as PaymentAttemptParams,
     type PaymentCancelParams as PaymentCancelParams,
   };
+
+  export {
+    Settings as Settings,
+    type SettingUpsertAvalaraCredentialsResponse as SettingUpsertAvalaraCredentialsResponse,
+    type SettingUpsertAvalaraCredentialsParams as SettingUpsertAvalaraCredentialsParams,
+  };
 }

package/src/resources/v2/contracts.ts

@@ -1701,7 +1701,8 @@ export namespace ContractEditParams {
         | 'azure_marketplace'
         | 'quickbooks_online'
         | 'workday'
-        | 'gcp_marketplace';
+        | 'gcp_marketplace'
+        | 'metronome';
 
       billing_provider_configuration_id?: string;
 
@@ -2610,7 +2611,9 @@ export namespace ContractEditParams {
       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. (BETA)
+       * If set to INDIVIDUAL, each seat in the subscription will have its own
+       * allocation.
        */
       allocation?: 'POOLED' | 'INDIVIDUAL';
     }
@@ -2773,7 +2776,9 @@ export namespace ContractEditParams {
       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. (BETA)
+       * If set to INDIVIDUAL, each seat in the subscription will have its own
+       * allocation.
        */
       allocation?: 'POOLED' | 'INDIVIDUAL';
     }
@@ -2994,6 +2999,11 @@ export namespace ContractEditParams {
      * 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
+     * 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';
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.0.0'; // x-release-please-version
+export const VERSION = '2.1.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.0.0";
+export declare const VERSION = "2.1.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.0.0";
+export declare const VERSION = "2.1.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '2.0.0'; // x-release-please-version
+exports.VERSION = '2.1.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '2.0.0'; // x-release-please-version
+export const VERSION = '2.1.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map