metronome-sdk 0.3.0 → 2.0.0

data/rbi/metronome_sdk/resources/v1/customers/invoices.rbi

@@ -5,7 +5,46 @@ module MetronomeSDK
     class V1
       class Customers
         class Invoices
-          # Fetch a specific invoice for a given customer.
+          # Retrieve detailed information for a specific invoice by its unique identifier.
+          # This endpoint returns comprehensive invoice data including line items, applied
+          # credits, totals, and billing period details for both finalized and draft
+          # invoices.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Display historical invoice details in customer-facing dashboards or billing
+          #   portals.
+          # - Retrieve current month draft invoices to show customers their month-to-date
+          #   spend.
+          # - Access finalized invoices for historical billing records and payment
+          #   reconciliation.
+          # - Validate customer pricing and credit applications for customer support
+          #   queries.
+          #
+          # ### Key response fields:
+          #
+          # Invoice status (DRAFT, FINALIZED, VOID) Billing period start and end dates Total
+          # amount and amount due after credits Detailed line items broken down by:
+          #
+          # - Customer and contract information
+          # - Invoice line item type
+          # - Product/service name and ID
+          # - Quantity consumed
+          # - Unit and total price
+          # - Time period for usage-based charges
+          # - Applied credits or prepaid commitments
+          #
+          # ### Usage guidelines:
+          #
+          # - Draft invoices update in real-time as usage is reported and may change before
+          #   finalization
+          # - The response includes both usage-based line items (e.g., API calls, data
+          #   processed) and scheduled charges (e.g., monthly subscriptions, commitment
+          #   fees)
+          # - Credit and commitment applications are shown as separate line items with
+          #   negative amounts
+          # - For voided invoices, the response will indicate VOID status but retain all
+          #   original line item details
           sig do
             params(
               customer_id: String,
@@ -28,8 +67,52 @@ module MetronomeSDK
           )
           end
 
-          # List all invoices for a given customer, optionally filtered by status, date
-          # range, and/or credit type.
+          # Retrieves a paginated list of invoices for a specific customer, with flexible
+          # filtering options to narrow results by status, date range, credit type, and
+          # more. This endpoint provides a comprehensive view of a customer's billing
+          # history and current charges, supporting both real-time billing dashboards and
+          # historical reporting needs.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Display historical invoice details in customer-facing dashboards or billing
+          #   portals.
+          # - Retrieve current month draft invoices to show customers their month-to-date
+          #   spend.
+          # - Access finalized invoices for historical billing records and payment
+          #   reconciliation.
+          # - Validate customer pricing and credit applications for customer support
+          #   queries.
+          # - Generate financial reports by filtering invoices within specific date ranges
+          #
+          # ### Key response fields:
+          #
+          # Array of invoice objects containing:
+          #
+          # - Invoice ID and status (DRAFT, FINALIZED, VOID)
+          # - Invoice type (USAGE, SCHEDULED)
+          # - Billing period start and end dates
+          # - Issue date and due date
+          # - Total amount, subtotal, and amount due
+          # - Applied credits summary
+          # - Contract ID reference
+          # - External billing provider status (if integrated with Stripe, etc.)
+          # - Pagination metadata `next_page` cursor
+          #
+          # ### Usage guidelines:
+          #
+          # - The endpoint returns invoice summaries; use the Get Invoice endpoint for
+          #   detailed line items
+          # - Draft invoices are continuously updated as new usage is reported and will show
+          #   real-time spend
+          # - Results are ordered by creation date descending by default (newest first)
+          # - When filtering by date range, the filter applies to the billing period, not
+          #   the issue date
+          # - For customers with many invoices, implement pagination to ensure all results
+          #   are retrieved External billing provider statuses (like Stripe payment status)
+          #   are included when applicable
+          # - Voided invoices are included in results by default unless filtered out by
+          #   status
           sig do
             params(
               customer_id: String,
@@ -113,11 +196,44 @@ module MetronomeSDK
           )
           end
 
-          # List daily or hourly invoice breakdowns for a given customer, optionally
-          # filtered by status, date range, and/or credit type. Important considerations:
+          # Retrieve granular time-series breakdowns of invoice data at hourly or daily
+          # intervals. This endpoint transforms standard invoices into detailed timelines,
+          # enabling you to track usage patterns, identify consumption spikes, and provide
+          # customers with transparency into their billing details throughout the billing
+          # period.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Build usage analytics dashboards showing daily or hourly consumption trends
+          # - Identify peak usage periods for capacity planning and cost optimization
+          # - Generate detailed billing reports for finance teams and customer success
+          # - Troubleshoot billing disputes by examining usage patterns at specific times
+          # - Power real-time cost monitoring and alerting systems
+          #
+          # ### Key response fields:
           #
-          # - If we receive backdated usage after an invoice has been finalized, the
-          #   backdated usage will be included in the response and usage numbers may differ.
+          # An array of BreakdownInvoice objects, each containing:
+          #
+          # - All standard invoice fields (ID, customer, commit, line items, totals, status)
+          # - Line items with quantities and costs for that specific period
+          # - `breakdown_start_timestamp`: Start of the specific time window
+          # - `breakdown_end_timestamp`: End of the specific time window
+          # - `next_page`: Pagination cursor for large result sets
+          #
+          # ### Usage guidelines:
+          #
+          # - Time granularity: Set `window_size` to hour or day based on your analysis
+          #   needs
+          # - Response limits: Daily breakdowns return up to 35 days; hourly breakdowns
+          #   return up to 24 hours per request
+          # - Date filtering: Use `starting_on` and `ending_before` to focus on specific
+          #   periods
+          # - Performance: For large date ranges, use pagination to retrieve all data
+          #   efficiently
+          # - Backdated usage: If usage events arrive after invoice finalization, breakdowns
+          #   will reflect the updated usage
+          # - Zero quantity filtering: Use `skip_zero_qty_line_items=true` to exclude
+          #   periods with no usage
           sig do
             params(
               customer_id: String,
@@ -171,6 +287,42 @@ module MetronomeSDK
           )
           end
 
+          # 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`)
+          sig do
+            params(
+              customer_id: String,
+              invoice_id: String,
+              request_options: MetronomeSDK::RequestOptions::OrHash
+            ).returns(StringIO)
+          end
+          def retrieve_pdf(customer_id:, invoice_id:, request_options: {})
+          end
+
           # @api private
           sig { params(client: MetronomeSDK::Client).returns(T.attached_class) }
           def self.new(client:)

data/rbi/metronome_sdk/resources/v1/customers.rbi

@@ -25,7 +25,40 @@ module MetronomeSDK
         sig { returns(MetronomeSDK::Resources::V1::Customers::NamedSchedules) }
         attr_reader :named_schedules
 
-        # Create a new customer
+        # Create a new customer in Metronome and optionally the billing configuration
+        # (recommended) which dictates where invoices for the customer will be sent or
+        # where payment will be collected.
+        #
+        # ### Use this endpoint to:
+        #
+        # Execute your customer provisioning workflows for either PLG motions, where
+        # customers originate in your platform, or SLG motions, where customers originate
+        # in your sales system.
+        #
+        # ### Key response fields:
+        #
+        # This end-point returns the `customer_id` created by the request. This id can be
+        # used to fetch relevant billing configurations and create contracts.
+        #
+        # ### Example workflow:
+        #
+        # - Generally, Metronome recommends first creating the customer in the downstream
+        #   payment / ERP system when payment method is collected and then creating the
+        #   customer in Metronome using the response (i.e. `customer_id`) from the
+        #   downstream system. If you do not create a billing configuration on customer
+        #   creation, you can add it later.
+        # - Once a customer is created, you can then create a contract for the customer.
+        #   In the contract creation process, you will need to add the customer billing
+        #   configuration to the contract to ensure Metronome invoices the customer
+        #   correctly. This is because a customer can have multiple configurations.
+        # - As part of the customer creation process, set the ingest alias for the
+        #   customer which will ensure usage is accurately mapped to the customer. Ingest
+        #   aliases can be added or changed after the creation process as well.
+        #
+        # ### Usage guidelines:
+        #
+        # For details on different billing configurations for different systems, review
+        # the `/setCustomerBillingConfiguration` end-point.
         sig do
           params(
             name: String,
@@ -45,6 +78,7 @@ module MetronomeSDK
           # This will be truncated to 160 characters if the provided name is longer.
           name:,
           billing_config: nil,
+          # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           custom_fields: nil,
           customer_billing_provider_configurations: nil,
           # (deprecated, use ingest_aliases instead) an alias that can be used to refer to
@@ -56,7 +90,13 @@ module MetronomeSDK
         )
         end
 
-        # Get a customer by Metronome ID.
+        # Get detailed information for a specific customer by their Metronome ID. Returns
+        # customer profile data including name, creation date, ingest aliases,
+        # configuration settings, and custom fields. Use this endpoint to fetch complete
+        # customer details for billing operations or account management.
+        #
+        # Note: If searching for a customer billing configuration, use the
+        # `/getCustomerBillingConfigurations` endpoint.
         sig do
           params(
             customer_id: String,
@@ -66,7 +106,11 @@ module MetronomeSDK
         def retrieve(customer_id:, request_options: {})
         end
 
-        # List all customers.
+        # Gets a paginated list of all customers in your Metronome account. Use this
+        # endpoint to browse your customer base, implement customer search functionality,
+        # or sync customer data with external systems. Returns customer details including
+        # IDs, names, and configuration settings. Supports filtering and pagination
+        # parameters for efficient data retrieval.
         sig do
           params(
             customer_ids: T::Array[String],
@@ -99,8 +143,20 @@ module MetronomeSDK
         )
         end
 
-        # Archive a customer Note: any alerts associated with the customer will not be
-        # triggered.
+        # Use this endpoint to archive a customer while preserving auditability. Archiving
+        # a customer will automatically archive all contracts as of the current date and
+        # void all corresponding invoices. Use this endpoint if a customer is onboarded by
+        # mistake.
+        #
+        # ### Usage guidelines:
+        #
+        # - Once a customer is archived, it cannot be unarchived.
+        # - Archived customers can still be viewed through the API or the UI for audit
+        #   purposes.
+        # - 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 notifications associated with the customer will no longer be triggered.
         sig do
           params(
             id: String,
@@ -110,7 +166,10 @@ module MetronomeSDK
         def archive(id:, request_options: {})
         end
 
-        # Get all billable metrics for a given customer.
+        # Get all billable metrics available for a specific customer. Supports pagination
+        # and filtering by current plan status or archived metrics. Use this endpoint to
+        # see which metrics are being tracked for billing calculations for a given
+        # customer.
         sig do
           params(
             customer_id: String,
@@ -173,10 +232,10 @@ module MetronomeSDK
         )
         end
 
-        # 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.
         sig do
           params(
             customer_id: String,
@@ -206,9 +265,91 @@ module MetronomeSDK
         )
         end
 
-        # Sets the ingest aliases for a customer. Ingest aliases can be used in the
-        # `customer_id` field when sending usage events to Metronome. This call is
-        # idempotent. It fully replaces the set of ingest aliases for the given customer.
+        # Returns all billing configurations previously set for the customer. Use during
+        # the contract provisioning process to fetch the
+        # `billing_provider_configuration_id` needed to set the contract billing
+        # configuration.
+        sig do
+          params(
+            customer_id: String,
+            include_archived: T::Boolean,
+            request_options: MetronomeSDK::RequestOptions::OrHash
+          ).returns(
+            MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse
+          )
+        end
+        def retrieve_billing_configurations(
+          customer_id:,
+          include_archived: nil,
+          request_options: {}
+        )
+        end
+
+        # Create a billing configuration for a customer. Once created, these
+        # configurations are available to associate to a contract and dictates which
+        # downstream system to collect payment in or send the invoice to. You can create
+        # multiple configurations per customer. The configuration formats are distinct for
+        # each downstream provider.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Add the initial configuration to an existing customer. Once created, the
+        #   billing configuration can then be associated to the customer's contract.
+        # - Add a new configuration to an existing customer. This might be used as part of
+        #   an upgrade or downgrade workflow where the customer was previously billed
+        #   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:
+        #
+        # - `direct_to_billing_provider`: Use when Metronome should send invoices directly
+        #   to the billing provider's API (e.g., Stripe, NetSuite). This is the most
+        #   common method for automated billing workflows.
+        # - `tackle`: Use specifically for AWS Marketplace transactions that require
+        #   Tackle's co-selling platform for partner attribution and commission tracking.
+        # - `aws_sqs`: Use when you want invoice data delivered to an AWS SQS queue for
+        #   custom processing before sending to your billing system.
+        # - `aws_sns`: Use when you want invoice notifications published to an AWS SNS
+        #   topic for event-driven billing workflows.
+        #
+        # ### Key response fields:
+        #
+        # The id for the customer billing configuration. This id can be used to associate
+        # the billing configuration to a contract.
+        #
+        # ### Usage guidelines:
+        #
+        # Must use the `delivery_method_id` if you have multiple Stripe accounts connected
+        # to Metronome.
+        sig do
+          params(
+            data:
+              T::Array[
+                MetronomeSDK::V1::CustomerSetBillingConfigurationsParams::Data::OrHash
+              ],
+            request_options: MetronomeSDK::RequestOptions::OrHash
+          ).void
+        end
+        def set_billing_configurations(data:, request_options: {})
+        end
+
+        # Sets the ingest aliases for a customer. Use this endpoint to associate a
+        # Metronome customer with an internal ID for easier tracking between systems.
+        # Ingest aliases can be used in the `customer_id` field when sending usage events
+        # to Metronome.
+        #
+        # ### Usage guidelines:
+        #
+        # - This call is idempotent and fully replaces the set of ingest aliases for the
+        #   given customer.
+        # - Switching an ingest alias from one customer to another will associate all
+        #   corresponding usage to the new customer.
+        # - Use multiple ingest aliases to model child organizations within a single
+        #   Metronome customer.
         sig do
           params(
             customer_id: String,
@@ -225,7 +366,11 @@ module MetronomeSDK
         )
         end
 
-        # Updates the specified customer's name.
+        # Updates the display name for a customer record. Use this to correct customer
+        # names, update business names after rebranding, or maintain accurate customer
+        # information for invoicing and reporting. Returns the updated customer object
+        # with the new name applied immediately across all billing documents and
+        # interfaces.
         sig do
           params(
             customer_id: String,
@@ -243,7 +388,10 @@ module MetronomeSDK
         )
         end
 
-        # Updates the specified customer's config.
+        # Update configuration settings for a specific customer, such as external system
+        # integrations (e.g., Salesforce account ID) and other customer-specific billing
+        # parameters. Use this endpoint to modify customer configurations without
+        # affecting core customer data like name or ingest aliases.
         sig do
           params(
             customer_id: String,

data/rbi/metronome_sdk/resources/v1/dashboards.rbi

@@ -4,9 +4,35 @@ module MetronomeSDK
   module Resources
     class V1
       class Dashboards
-        # Retrieve an embeddable dashboard url for a customer. The dashboard can be
-        # embedded using an iframe in a website. This will show information such as usage
-        # data and customer invoices.
+        # Generate secure, embeddable dashboard URLs that allow you to seamlessly
+        # integrate Metronome's billing visualizations directly into your application.
+        # This endpoint creates authenticated iframe-ready URLs for customer-specific
+        # dashboards, providing a white-labeled billing experience without building custom
+        # UI.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Embed billing dashboards directly in your customer portal or admin interface
+        # - Provide self-service access to invoices, usage data, and credit balances
+        # - Build white-labeled billing experiences with minimal development effort
+        #
+        # ### Key response fields:
+        #
+        # - A secure, time-limited URL that can be embedded in an iframe
+        # - The URL includes authentication tokens and configuration parameters
+        # - URLs are customer-specific and respect your security settings
+        #
+        # ### Usage guidelines:
+        #
+        # - Dashboard types: Choose from `invoices`, `usage`, or `commits_and_credits`
+        # - Customization options:
+        #   - `dashboard_options`: Configure whether you want invoices to show zero usage
+        #     line items
+        #   - `color_overrides`: Match your brand's color palette
+        #   - `bm_group_key_overrides`: Customize how dimensions are displayed (for the
+        #     usage embeddable dashboard)
+        # - Iframe implementation: Embed the returned URL directly in an iframe element
+        # - Responsive design: Dashboards automatically adapt to container dimensions
         sig do
           params(
             customer_id: String,

data/rbi/metronome_sdk/resources/v1/invoices.rbi

@@ -4,7 +4,24 @@ module MetronomeSDK
   module Resources
     class V1
       class Invoices
-        # Regenerate a voided contract invoice
+        # This endpoint regenerates a voided invoice and recalculates the invoice based on
+        # up-to-date rates, available balances, and other fees regardless of the billing
+        # period.
+        #
+        # ### Use this endpoint to:
+        #
+        # Recalculate an invoice with updated rate terms, available balance, and fees to
+        # correct billing disputes or discrepancies
+        #
+        # ### Key response fields:
+        #
+        # The regenerated invoice id, which is distinct from the previously voided
+        # invoice.
+        #
+        # ### Usage guidelines:
+        #
+        # If an invoice is attached to a contract with a billing provider on it, the
+        # regenerated invoice will be distributed based on the configuration.
         sig do
           params(
             id: String,
@@ -18,7 +35,11 @@ module MetronomeSDK
         )
         end
 
-        # Void an invoice
+        # Permanently cancels an invoice by setting its status to voided, preventing
+        # collection and removing it from customer billing. Use this to correct billing
+        # errors, cancel incorrect charges, or handle disputed invoices that should not be
+        # collected. Returns the voided invoice ID with the status change applied
+        # immediately to stop any payment processing.
         sig do
           params(
             id: String,

data/rbi/metronome_sdk/resources/v1/payments.rbi

@@ -0,0 +1,72 @@
+# typed: strong
+
+module MetronomeSDK
+  module Resources
+    class V1
+      class Payments
+        # Fetch all payment attempts for the given invoice.
+        sig do
+          params(
+            customer_id: String,
+            invoice_id: String,
+            limit: Integer,
+            next_page: String,
+            statuses: T::Array[MetronomeSDK::V1::PaymentStatus::OrSymbol],
+            request_options: MetronomeSDK::RequestOptions::OrHash
+          ).returns(
+            MetronomeSDK::Internal::BodyCursorPage[MetronomeSDK::V1::Payment]
+          )
+        end
+        def list(
+          customer_id:,
+          invoice_id:,
+          # The maximum number of payments to return. Defaults to 25.
+          limit: nil,
+          # The next page token from a previous response.
+          next_page: nil,
+          statuses: nil,
+          request_options: {}
+        )
+        end
+
+        # 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.
+        sig do
+          params(
+            customer_id: String,
+            invoice_id: String,
+            request_options: MetronomeSDK::RequestOptions::OrHash
+          ).returns(MetronomeSDK::Models::V1::PaymentAttemptResponse)
+        end
+        def attempt(customer_id:, invoice_id:, request_options: {})
+        end
+
+        # Cancel an existing payment attempt for an invoice.
+        sig do
+          params(
+            customer_id: String,
+            invoice_id: String,
+            request_options: MetronomeSDK::RequestOptions::OrHash
+          ).returns(MetronomeSDK::Models::V1::PaymentCancelResponse)
+        end
+        def cancel(customer_id:, invoice_id:, request_options: {})
+        end
+
+        # @api private
+        sig { params(client: MetronomeSDK::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/metronome_sdk/resources/v1/pricing_units.rbi

@@ -4,7 +4,12 @@ module MetronomeSDK
   module Resources
     class V1
       class PricingUnits
-        # List all pricing units (known in the API by the legacy term "credit types").
+        # List all pricing units. All fiat currency types (for example, USD or GBP) will
+        # be included, as well as any custom pricing units that were configured. Custom
+        # pricing units can be used to charge for usage in a non-fiat pricing unit, for
+        # example AI credits.
+        #
+        # Note: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.
         sig do
           params(
             limit: Integer,

data/rbi/metronome_sdk/resources/v1/services.rbi

@@ -4,10 +4,12 @@ module MetronomeSDK
   module Resources
     class V1
       class Services
-        # Fetches a list of services used by Metronome and the associated IP addresses. IP
-        # addresses are not necessarily unique between services. In most cases, IP
-        # addresses will appear in the list at least 30 days before they are used for the
-        # first time.
+        # Gets Metronome's service registry with associated IP addresses for security
+        # allowlisting and firewall configuration. Use this endpoint to maintain an
+        # up-to-date list of IPs that your systems should trust for Metronome
+        # communications. Returns service names and their current IP ranges, with new IPs
+        # typically appearing 30+ days before first use to ensure smooth allowlist
+        # updates.
         sig do
           params(request_options: MetronomeSDK::RequestOptions::OrHash).returns(
             MetronomeSDK::Models::V1::ServiceListResponse