@metronome/sdk 1.0.0 → 2.1.0

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

@@ -70,6 +70,7 @@ export {
   type InvoiceListParams,
   type InvoiceAddChargeParams,
   type InvoiceListBreakdownsParams,
+  type InvoiceRetrievePdfParams,
   type InvoicesCursorPage,
   type InvoiceListBreakdownsResponsesCursorPage,
 } from './invoices';

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

@@ -4,6 +4,7 @@ import { APIResource } from '../../../core/resource';
 import * as Shared from '../../shared';
 import { APIPromise } from '../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -132,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
@@ -219,6 +221,55 @@ export class Invoices extends APIResource {
       { query, ...options },
     );
   }
+
+  /**
+   * Retrieve a PDF version of a specific invoice by its unique identifier. This
+   * endpoint generates a professionally formatted invoice document suitable for
+   * sharing with customers, accounting teams, or for record-keeping purposes.
+   *
+   * ### Use this endpoint to:
+   *
+   * - Provide customers with downloadable or emailable copies of their invoices
+   * - Support accounting and finance teams with official billing documents
+   * - Maintain accurate records of billing transactions for audits and compliance
+   *
+   * ### Key response details:
+   *
+   * - The response is a binary PDF file representing the full invoice
+   * - The PDF includes all standard invoice information such as line items, totals,
+   *   billing period, and customer details
+   * - The document is formatted for clarity and professionalism, suitable for
+   *   official use
+   *
+   * ### Usage guidelines:
+   *
+   * - Ensure the `invoice_id` corresponds to an existing invoice for the specified
+   *   `customer_id`
+   * - The PDF is generated on-demand; frequent requests for the same invoice may
+   *   impact performance
+   * - Use appropriate headers to handle the binary response in your application
+   *   (e.g., setting `Content-Type: application/pdf`)
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.invoices.retrievePdf({
+   *     customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+   *     invoice_id: '6a37bb88-8538-48c5-b37b-a41c836328bd',
+   *   });
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
+   */
+  retrievePdf(params: InvoiceRetrievePdfParams, options?: RequestOptions): APIPromise<Response> {
+    const { customer_id, invoice_id } = params;
+    return this._client.get(path`/v1/customers/${customer_id}/invoices/${invoice_id}/pdf`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/pdf' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
 }
 
 export type InvoicesCursorPage = CursorPage<Invoice>;
@@ -245,7 +296,13 @@ export interface Invoice {
   /**
    * This field's availability is dependent on your client's configuration.
    */
-  billable_status?: 'billable' | 'unbillable';
+  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" }
@@ -290,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" }
    */
@@ -434,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.
      */
@@ -534,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.
      */
@@ -617,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;
 
@@ -637,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'
@@ -654,7 +753,49 @@ export namespace Invoice {
 
       invoice_id?: string;
 
+      /**
+       * The subtotal amount invoiced, if available from the billing provider.
+       */
+      invoiced_sub_total?: number;
+
+      /**
+       * The total amount invoiced, if available from the billing provider.
+       */
+      invoiced_total?: number;
+
       issued_at_timestamp?: string;
+
+      /**
+       * A URL to the PDF of the invoice, if available from the billing provider.
+       */
+      pdf_url?: string;
+
+      /**
+       * Tax details for the invoice, if available from the billing provider.
+       */
+      tax?: CorrectedExternalInvoice.Tax;
+    }
+
+    export namespace CorrectedExternalInvoice {
+      /**
+       * Tax details for the invoice, if available from the billing provider.
+       */
+      export interface Tax {
+        /**
+         * The total tax amount applied to the invoice.
+         */
+        total_tax_amount?: number;
+
+        /**
+         * The total taxable amount of the invoice.
+         */
+        total_taxable_amount?: number;
+
+        /**
+         * The transaction ID associated with the tax calculation.
+         */
+        transaction_id?: string;
+      }
     }
   }
 
@@ -667,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'
@@ -684,7 +831,49 @@ export namespace Invoice {
 
     invoice_id?: string;
 
+    /**
+     * The subtotal amount invoiced, if available from the billing provider.
+     */
+    invoiced_sub_total?: number;
+
+    /**
+     * The total amount invoiced, if available from the billing provider.
+     */
+    invoiced_total?: number;
+
     issued_at_timestamp?: string;
+
+    /**
+     * A URL to the PDF of the invoice, if available from the billing provider.
+     */
+    pdf_url?: string;
+
+    /**
+     * Tax details for the invoice, if available from the billing provider.
+     */
+    tax?: ExternalInvoice.Tax;
+  }
+
+  export namespace ExternalInvoice {
+    /**
+     * Tax details for the invoice, if available from the billing provider.
+     */
+    export interface Tax {
+      /**
+       * The total tax amount applied to the invoice.
+       */
+      total_tax_amount?: number;
+
+      /**
+       * The total taxable amount of the invoice.
+       */
+      total_taxable_amount?: number;
+
+      /**
+       * The transaction ID associated with the tax calculation.
+       */
+      transaction_id?: string;
+    }
   }
 
   export interface InvoiceAdjustment {
@@ -702,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.
    */
@@ -891,6 +1090,12 @@ export interface InvoiceListBreakdownsParams extends CursorPageParams {
   window_size?: 'HOUR' | 'DAY';
 }
 
+export interface InvoiceRetrievePdfParams {
+  customer_id: string;
+
+  invoice_id: string;
+}
+
 export declare namespace Invoices {
   export {
     type Invoice as Invoice,
@@ -903,5 +1108,6 @@ export declare namespace Invoices {
     type InvoiceListParams as InvoiceListParams,
     type InvoiceAddChargeParams as InvoiceAddChargeParams,
     type InvoiceListBreakdownsParams as InvoiceListBreakdownsParams,
+    type InvoiceRetrievePdfParams as InvoiceRetrievePdfParams,
   };
 }

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

@@ -121,6 +121,17 @@ export {
   type InvoiceRegenerateParams,
   type InvoiceVoidParams,
 } from './invoices';
+export {
+  Payments,
+  type Payment,
+  type PaymentStatus,
+  type PaymentAttemptResponse,
+  type PaymentCancelResponse,
+  type PaymentListParams,
+  type PaymentAttemptParams,
+  type PaymentCancelParams,
+  type PaymentsBodyCursorPage,
+} from './payments';
 export {
   Plans,
   type PlanDetail,
@@ -143,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

@@ -0,0 +1,172 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { BodyCursorPage, type BodyCursorPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Payments extends APIResource {
+  /**
+   * Fetch all payment attempts for the given invoice.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const payment of client.v1.payments.list({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   *   statuses: ['pending', 'requires_intervention'],
+   * })) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(body: PaymentListParams, options?: RequestOptions): PagePromise<PaymentsBodyCursorPage, Payment> {
+    return this._client.getAPIList('/v1/payments/list', BodyCursorPage<Payment>, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+
+  /**
+   * Trigger a new attempt by canceling any existing attempts for this invoice and
+   * creating a new Payment. This will trigger another attempt to charge the
+   * Customer's configured Payment Gateway. Payment can only be attempted if all of
+   * the following are true:
+   *
+   * - The Metronome Invoice is finalized
+   * - PLG Invoicing is configured for the Customer
+   * - You cannot attempt payments for invoices that have already been `paid` or
+   *   `voided`.
+   *
+   * Attempting to payment on an ineligible Invoice or Customer will result in a
+   * `400` response.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.payments.attempt({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   * });
+   * ```
+   */
+  attempt(body: PaymentAttemptParams, options?: RequestOptions): APIPromise<PaymentAttemptResponse> {
+    return this._client.post('/v1/payments/attempt', { body, ...options });
+  }
+
+  /**
+   * Cancel an existing payment attempt for an invoice.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.payments.cancel({
+   *   customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+   *   invoice_id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85',
+   * });
+   * ```
+   */
+  cancel(body: PaymentCancelParams, options?: RequestOptions): APIPromise<PaymentCancelResponse> {
+    return this._client.post('/v1/payments/cancel', { body, ...options });
+  }
+}
+
+export type PaymentsBodyCursorPage = BodyCursorPage<Payment>;
+
+export interface Payment {
+  id: string;
+
+  amount?: number;
+
+  amount_paid?: number;
+
+  contract_id?: string;
+
+  created_at?: string;
+
+  customer_id?: string;
+
+  error_message?: string;
+
+  fiat_credit_type?: Shared.CreditTypeData;
+
+  invoice_id?: string;
+
+  payment_gateway?: Payment.PaymentGateway;
+
+  status?: PaymentStatus;
+
+  updated_at?: string;
+}
+
+export namespace Payment {
+  export interface PaymentGateway {
+    stripe: PaymentGateway.Stripe;
+
+    type: 'stripe';
+  }
+
+  export namespace PaymentGateway {
+    export interface Stripe {
+      payment_intent_id: string;
+
+      error?: Stripe.Error;
+
+      payment_method_id?: string;
+    }
+
+    export namespace Stripe {
+      export interface Error {
+        code?: string;
+
+        decline_code?: string;
+
+        type?: string;
+      }
+    }
+  }
+}
+
+export type PaymentStatus = 'pending' | 'requires_intervention' | 'paid' | 'canceled';
+
+export interface PaymentAttemptResponse {
+  data: Payment;
+}
+
+export interface PaymentCancelResponse {
+  data: Payment;
+}
+
+export interface PaymentListParams extends BodyCursorPageParams {
+  customer_id: string;
+
+  invoice_id: string;
+
+  statuses?: Array<PaymentStatus>;
+}
+
+export interface PaymentAttemptParams {
+  customer_id: string;
+
+  invoice_id: string;
+}
+
+export interface PaymentCancelParams {
+  customer_id: string;
+
+  invoice_id: string;
+}
+
+export declare namespace Payments {
+  export {
+    type Payment as Payment,
+    type PaymentStatus as PaymentStatus,
+    type PaymentAttemptResponse as PaymentAttemptResponse,
+    type PaymentCancelResponse as PaymentCancelResponse,
+    type PaymentsBodyCursorPage as PaymentsBodyCursorPage,
+    type PaymentListParams as PaymentListParams,
+    type PaymentAttemptParams as PaymentAttemptParams,
+    type PaymentCancelParams as PaymentCancelParams,
+  };
+}

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