@metronome/sdk 2.0.0 → 2.2.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',
    * });
    * ```
    */
@@ -369,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',
@@ -395,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',
+   *     },
    *   ],
    * });
    * ```
@@ -402,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 });
   }
 
   /**
@@ -728,7 +733,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
@@ -756,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;
 }
@@ -775,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
@@ -799,7 +855,12 @@ export namespace CustomerCreateParams {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | '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.
@@ -835,6 +896,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'
@@ -876,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 {
@@ -952,20 +1043,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 +1106,8 @@ export namespace CustomerSetBillingConfigurationsParams {
       | 'azure_marketplace'
       | 'quickbooks_online'
       | 'workday'
-      | 'gcp_marketplace';
+      | 'gcp_marketplace'
+      | 'metronome';
 
     customer_id: string;
 
@@ -1113,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

@@ -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,12 +730,24 @@ 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;
+
+      /**
+       * 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'
@@ -759,12 +814,24 @@ 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;
+
+    /**
+     * 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'
@@ -836,6 +903,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
@@ -180,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,
@@ -154,6 +155,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' | 'gcp_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';