@metronome/sdk 1.0.0 → 2.0.0

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

@@ -48,6 +48,7 @@ import {
   InvoiceListBreakdownsResponsesCursorPage,
   InvoiceListParams,
   InvoiceRetrieveParams,
+  InvoiceRetrievePdfParams,
   InvoiceRetrieveResponse,
   Invoices,
   InvoicesCursorPage,
@@ -203,7 +204,7 @@ export class Customers extends APIResource {
    * - Ingest aliases remain idempotent for archived customers. In order to reuse an
    *   ingest alias, first remove the ingest alias from the customer prior to
    *   archiving.
-   * - Any alerts associated with the customer will no longer be triggered.
+   * - Any notifications associated with the customer will no longer be triggered.
    *
    * @example
    * ```ts
@@ -276,10 +277,10 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Preview how a set of events will affect a customer's invoice. Generates a draft
-   * invoice for a customer using their current contract configuration and the
+   * 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 invoice before they are actually processed.
+   * customer's invoices before they are actually processed.
    *
    * @example
    * ```ts
@@ -340,6 +341,9 @@ export class Customers extends APIResource {
    *   through system A (e.g. Stripe) but will now be billed through system B (e.g.
    *   AWS). Once created, the new configuration can then be associated to the
    *   customer's contract.
+   * - Multiple configurations can be added per destination. For example, you can
+   *   create two Stripe billing configurations for a Metronome customer that each
+   *   have a distinct `collection_method`.
    *
    * ### Delivery method options:
    *
@@ -546,6 +550,11 @@ export interface CustomerDetail {
 
   name: string;
 
+  /**
+   * RFC 3339 timestamp indicating when the customer was last updated.
+   */
+  updated_at: string;
+
   /**
    * RFC 3339 timestamp indicating when the customer was archived. Null if the
    * customer is active.
@@ -691,7 +700,7 @@ export namespace CustomerListCostsResponse {
 }
 
 export interface CustomerPreviewEventsResponse {
-  data: InvoicesAPI.Invoice;
+  data: Array<InvoicesAPI.Invoice>;
 }
 
 export interface CustomerRetrieveBillingConfigurationsResponse {
@@ -966,13 +975,6 @@ export namespace CustomerPreviewEventsParams {
   export interface Event {
     event_type: string;
 
-    /**
-     * This has no effect for preview events, but may be set for consistency with Event
-     * objects. They will be processed even if they do not match the customer's ID or
-     * ingest aliases.
-     */
-    customer_id?: string;
-
     properties?: { [key: string]: unknown };
 
     /**
@@ -981,9 +983,9 @@ export namespace CustomerPreviewEventsParams {
     timestamp?: string;
 
     /**
-     * This has no effect for preview events, but may be set for consistency with Event
-     * objects. Duplicate transaction_ids are NOT filtered out, even within the same
-     * request.
+     * Optional unique identifier for event deduplication. When provided, preview
+     * events are automatically deduplicated against historical events from the past 34
+     * days. Duplicate transaction IDs within the same request will return an error.
      */
     transaction_id?: string;
   }
@@ -1165,6 +1167,7 @@ export declare namespace Customers {
     type InvoiceListParams as InvoiceListParams,
     type InvoiceAddChargeParams as InvoiceAddChargeParams,
     type InvoiceListBreakdownsParams as InvoiceListBreakdownsParams,
+    type InvoiceRetrievePdfParams as InvoiceRetrievePdfParams,
   };
 
   export {

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';
 
@@ -219,6 +220,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 +295,7 @@ export interface Invoice {
   /**
    * This field's availability is dependent on your client's configuration.
    */
-  billable_status?: 'billable' | 'unbillable';
+  billable_status?: unknown;
 
   /**
    * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
@@ -654,7 +704,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;
+      }
     }
   }
 
@@ -684,7 +776,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 {
@@ -891,6 +1025,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 +1043,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/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,

package/src/resources/v1/payments.ts

@@ -0,0 +1,170 @@
+// 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;
+    }
+
+    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/usage.ts

@@ -81,8 +81,7 @@ export class Usage extends APIResource {
    * ingestion, supports backdating 34 days, and is built to handle mission-critical
    * usage data with enterprise-grade reliability. Metronome supports 100,000 events
    * per second without requiring pre-aggregation or rollups and can scale up from
-   * there. See
-   * [Getting usage into Metronome](https://docs.metronome.com/connect-metronome/) to
+   * there. See the [Send usage events](/guides/events/send-usage-events) guide to
    * learn more about usage events.
    *
    * ### Use this endpoint to:
@@ -125,6 +124,9 @@ export class Usage extends APIResource {
    * }
    * ```
    *
+   * Learn more about
+   * [usage event structure definitions](/guides/events/design-usage-events).
+   *
    * #### Transaction ID
    *
    * The transaction_id serves as your idempotency key, ensuring events are processed

package/src/resources/v1/v1.ts

@@ -69,6 +69,18 @@ import {
   InvoiceVoidResponse,
   Invoices,
 } from './invoices';
+import * as PaymentsAPI from './payments';
+import {
+  Payment,
+  PaymentAttemptParams,
+  PaymentAttemptResponse,
+  PaymentCancelParams,
+  PaymentCancelResponse,
+  PaymentListParams,
+  PaymentStatus,
+  Payments,
+  PaymentsBodyCursorPage,
+} from './payments';
 import * as PlansAPI from './plans';
 import {
   PlanDetail,
@@ -180,6 +192,7 @@ export class V1 extends APIResource {
   services: ServicesAPI.Services = new ServicesAPI.Services(this._client);
   invoices: InvoicesAPI.Invoices = new InvoicesAPI.Invoices(this._client);
   contracts: ContractsAPI.Contracts = new ContractsAPI.Contracts(this._client);
+  payments: PaymentsAPI.Payments = new PaymentsAPI.Payments(this._client);
 }
 
 V1.Alerts = Alerts;
@@ -195,6 +208,7 @@ V1.BillableMetrics = BillableMetrics;
 V1.Services = Services;
 V1.Invoices = Invoices;
 V1.Contracts = Contracts;
+V1.Payments = Payments;
 
 export declare namespace V1 {
   export {
@@ -364,4 +378,16 @@ export declare namespace V1 {
     type ContractSetUsageFilterParams as ContractSetUsageFilterParams,
     type ContractUpdateEndDateParams as ContractUpdateEndDateParams,
   };
+
+  export {
+    Payments as Payments,
+    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,
+  };
 }