metronome-sdk 0.3.0 → 2.0.0

data/lib/metronome_sdk/resources/v1/customers/invoices.rb

@@ -8,7 +8,46 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::InvoiceRetrieveParams} for more details.
           #
-          # 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
           #
           # @overload retrieve(customer_id:, invoice_id:, skip_zero_qty_line_items: nil, request_options: {})
           #
@@ -45,8 +84,52 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::InvoiceListParams} for more details.
           #
-          # 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
           #
           # @overload list(customer_id:, credit_type_id: nil, ending_before: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, starting_on: nil, status: nil, request_options: {})
           #
@@ -134,11 +217,44 @@ module MetronomeSDK
           # {MetronomeSDK::Models::V1::Customers::InvoiceListBreakdownsParams} for more
           # details.
           #
-          # List daily or hourly invoice breakdowns for a given customer, optionally
-          # filtered by status, date range, and/or credit type. Important considerations:
-          #
-          # - 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.
+          # 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:
+          #
+          # 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
           #
           # @overload list_breakdowns(customer_id:, ending_before:, starting_on:, credit_type_id: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, status: nil, window_size: nil, request_options: {})
           #
@@ -183,6 +299,61 @@ 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`)
+          #
+          # @overload retrieve_pdf(customer_id:, invoice_id:, request_options: {})
+          #
+          # @param customer_id [String]
+          # @param invoice_id [String]
+          # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [StringIO]
+          #
+          # @see MetronomeSDK::Models::V1::Customers::InvoiceRetrievePdfParams
+          def retrieve_pdf(params)
+            parsed, options = MetronomeSDK::V1::Customers::InvoiceRetrievePdfParams.dump_request(params)
+            customer_id =
+              parsed.delete(:customer_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            invoice_id =
+              parsed.delete(:invoice_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :get,
+              path: ["v1/customers/%1$s/invoices/%2$s/pdf", customer_id, invoice_id],
+              headers: {"accept" => "application/pdf"},
+              model: StringIO,
+              options: options
+            )
+          end
+
           # @api private
           #
           # @param client [MetronomeSDK::Client]

data/lib/metronome_sdk/resources/v1/customers.rb

@@ -28,7 +28,40 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerCreateParams} for more details.
         #
-        # 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.
         #
         # @overload create(name:, billing_config: nil, custom_fields: nil, customer_billing_provider_configurations: nil, external_id: nil, ingest_aliases: nil, request_options: {})
         #
@@ -36,7 +69,7 @@ module MetronomeSDK
         #
         # @param billing_config [MetronomeSDK::Models::V1::CustomerCreateParams::BillingConfig]
         #
-        # @param custom_fields [Hash{Symbol=>String}]
+        # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
         #
         # @param customer_billing_provider_configurations [Array<MetronomeSDK::Models::V1::CustomerCreateParams::CustomerBillingProviderConfiguration>]
         #
@@ -60,7 +93,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.
         #
         # @overload retrieve(customer_id:, request_options: {})
         #
@@ -87,7 +126,11 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerListParams} for more details.
         #
-        # 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.
         #
         # @overload list(customer_ids: nil, ingest_alias: nil, limit: nil, next_page: nil, only_archived: nil, salesforce_account_ids: nil, request_options: {})
         #
@@ -120,8 +163,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.
         #
         # @overload archive(id:, request_options: {})
         #
@@ -145,7 +200,10 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerListBillableMetricsParams} for more details.
         #
-        # 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.
         #
         # @overload list_billable_metrics(customer_id:, include_archived: nil, limit: nil, next_page: nil, on_current_plan: nil, request_options: {})
         #
@@ -220,10 +278,10 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerPreviewEventsParams} for more details.
         #
-        # 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.
         #
         # @overload preview_events(customer_id:, events:, mode: nil, skip_zero_qty_line_items: nil, request_options: {})
         #
@@ -255,9 +313,104 @@ 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.
+        #
+        # @overload retrieve_billing_configurations(customer_id:, include_archived: nil, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param include_archived [Boolean]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse]
+        #
+        # @see MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsParams
+        def retrieve_billing_configurations(params)
+          parsed, options = MetronomeSDK::V1::CustomerRetrieveBillingConfigurationsParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/getCustomerBillingProviderConfigurations",
+            body: parsed,
+            model: MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse,
+            options: 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.
+        #
+        # @overload set_billing_configurations(data:, request_options: {})
+        #
+        # @param data [Array<MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsParams::Data>]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsParams
+        def set_billing_configurations(params)
+          parsed, options = MetronomeSDK::V1::CustomerSetBillingConfigurationsParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/setCustomerBillingProviderConfigurations",
+            body: parsed,
+            model: NilClass,
+            options: 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.
         #
         # @overload set_ingest_aliases(customer_id:, ingest_aliases:, request_options: {})
         #
@@ -288,7 +441,11 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerSetNameParams} for more details.
         #
-        # 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.
         #
         # @overload set_name(customer_id:, name:, request_options: {})
         #
@@ -319,7 +476,10 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::CustomerUpdateConfigParams} for more details.
         #
-        # 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.
         #
         # @overload update_config(customer_id:, leave_stripe_invoices_in_draft: nil, salesforce_account_id: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/dashboards.rb

@@ -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
         #
         # @overload get_embeddable_url(customer_id:, dashboard:, bm_group_key_overrides: nil, color_overrides: nil, dashboard_options: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/invoices.rb

@@ -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.
         #
         # @overload regenerate(id:, request_options: {})
         #
@@ -26,7 +43,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.
         #
         # @overload void(id:, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/payments.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module MetronomeSDK
+  module Resources
+    class V1
+      class Payments
+        # Fetch all payment attempts for the given invoice.
+        #
+        # @overload list(customer_id:, invoice_id:, limit: nil, next_page: nil, statuses: nil, request_options: {})
+        #
+        # @param customer_id [String]
+        #
+        # @param invoice_id [String]
+        #
+        # @param limit [Integer] The maximum number of payments to return. Defaults to 25.
+        #
+        # @param next_page [String] The next page token from a previous response.
+        #
+        # @param statuses [Array<Symbol, MetronomeSDK::Models::V1::PaymentStatus>]
+        #
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::V1::Payment>]
+        #
+        # @see MetronomeSDK::Models::V1::PaymentListParams
+        def list(params)
+          parsed, options = MetronomeSDK::V1::PaymentListParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/payments/list",
+            body: parsed,
+            page: MetronomeSDK::Internal::BodyCursorPage,
+            model: MetronomeSDK::V1::Payment,
+            options: 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.
+        #
+        # @overload attempt(customer_id:, invoice_id:, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param invoice_id [String]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Models::V1::PaymentAttemptResponse]
+        #
+        # @see MetronomeSDK::Models::V1::PaymentAttemptParams
+        def attempt(params)
+          parsed, options = MetronomeSDK::V1::PaymentAttemptParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/payments/attempt",
+            body: parsed,
+            model: MetronomeSDK::Models::V1::PaymentAttemptResponse,
+            options: options
+          )
+        end
+
+        # Cancel an existing payment attempt for an invoice.
+        #
+        # @overload cancel(customer_id:, invoice_id:, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param invoice_id [String]
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Models::V1::PaymentCancelResponse]
+        #
+        # @see MetronomeSDK::Models::V1::PaymentCancelParams
+        def cancel(params)
+          parsed, options = MetronomeSDK::V1::PaymentCancelParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/payments/cancel",
+            body: parsed,
+            model: MetronomeSDK::Models::V1::PaymentCancelResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [MetronomeSDK::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/metronome_sdk/resources/v1/pricing_units.rb

@@ -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.
         #
         # @overload list(limit: nil, next_page: nil, request_options: {})
         #