metronome-sdk 1.0.0 → 2.1.0

data/rbi/metronome_sdk/resources/v1/alerts.rbi

@@ -4,16 +4,15 @@ module MetronomeSDK
   module Resources
     class V1
       class Alerts
-        # Create a new alert to monitor customer spending, balances, and billing metrics
-        # in real-time. Metronome's alert system provides industry-leading speed with
-        # immediate evaluation capabilities, enabling you to proactively manage customer
-        # accounts and prevent revenue leakage.
+        # Create a new threshold notification to monitor customer spending, balances, and
+        # billing metrics in real-time. Metronome's notification system provides
+        # industry-leading speed with immediate evaluation capabilities, enabling you to
+        # proactively manage customer accounts and prevent revenue leakage.
         #
-        # This endpoint creates configurable alerts that continuously monitor various
-        # billing thresholds including spend limits, credit balances, commitment
-        # utilization, and invoice totals. Alerts can be configured globally for all
-        # customers or targeted to specific customer accounts. Custom fields can be used
-        # on certain alert types to further target alerts to groups of customers.
+        # This endpoint creates configurable threshold notifications that continuously
+        # monitor various billing thresholds including spend limits, credit balances,
+        # commitment utilization, and invoice totals. Threshold notifications can be
+        # configured globally for all customers or targeted to specific customer accounts.
         #
         # ### Use this endpoint to:
         #
@@ -29,26 +28,27 @@ module MetronomeSDK
         #
         # A successful response returns a CustomerAlert object containing:
         #
-        # - The alert configuration with its unique ID and current status
+        # - The threshold notification configuration with its unique ID and current status
         # - The customer's evaluation status (ok, in_alarm, or evaluating)
-        # - Alert metadata including type, threshold values, and update timestamps
+        # - Threshold notification metadata including type, threshold values, and update
+        #   timestamps
         #
         # ### Usage guidelines:
         #
         # - Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant
         #   evaluation against existing customers
-        # - Uniqueness constraints: Each alert must have a unique `uniqueness_key` within
-        #   your organization. Use `release_uniqueness_key` : `true` when archiving to
-        #   reuse keys
-        # - Alert type requirements: Different alert types require specific fields (e.g.,
-        #   `billable_metric_id` for usage alerts, `credit_type_id` for credit-based
-        #   alerts)
-        # - Webhook delivery: Alerts trigger webhook notifications for real-time
-        #   integration with your systems. Configure webhook endpoints before creating
-        #   alerts
-        # - Performance at scale: Metronome's event-driven architecture processes alert
-        #   evaluations in real-time as usage events stream in, unlike competitors who
-        #   rely on periodic polling or batch evaluation cycles
+        # - Uniqueness constraints: Each threshold notification must have a unique
+        #   `uniqueness_key` within your organization. Use `release_uniqueness_key` :
+        #   `true` when archiving to reuse keys
+        # - Notification type requirements: Different threshold notification types require
+        #   specific fields (e.g., `billable_metric_id` for usage notifications,
+        #   `credit_type_id` for credit-based threshold notifications)
+        # - Webhook delivery: Threshold notifications trigger webhook notifications for
+        #   real-time integration with your systems. Configure webhook endpoints before
+        #   creating threshold notifications
+        # - Performance at scale: Metronome's event-driven architecture processes
+        #   threshold notification evaluations in real-time as usage events stream in,
+        #   unlike competitors who rely on periodic polling or batch evaluation cycles
         sig do
           params(
             alert_type:
@@ -73,42 +73,44 @@ module MetronomeSDK
           ).returns(MetronomeSDK::Models::V1::AlertCreateResponse)
         end
         def create(
-          # Type of the alert
+          # Type of the threshold notification
           alert_type:,
-          # Name of the alert
+          # Name of the threshold notification
           name:,
-          # Threshold value of the alert policy. Depending upon the alert type, this number
-          # may represent a financial amount, the days remaining, or a percentage reached.
+          # Threshold value of the notification policy. Depending upon the notification
+          # type, this number may represent a financial amount, the days remaining, or a
+          # percentage reached.
           threshold:,
-          # For alerts of type `usage_threshold_reached`, specifies which billable metric to
-          # track the usage for.
+          # For threshold notifications of type `usage_threshold_reached`, specifies which
+          # billable metric to track the usage for.
           billable_metric_id: nil,
-          # An array of strings, representing a way to filter the credit grant this alert
-          # applies to, by looking at the credit_grant_type field on the credit grant. This
-          # field is only defined for CreditPercentage and CreditBalance alerts
+          # An array of strings, representing a way to filter the credit grant this
+          # threshold notification applies to, by looking at the credit_grant_type field on
+          # the credit grant. This field is only defined for CreditPercentage and
+          # CreditBalance notifications
           credit_grant_type_filters: nil,
-          # ID of the credit's currency, defaults to USD. If the specific alert type
+          # ID of the credit's currency, defaults to USD. If the specific notification type
           # requires a pricing unit/currency, find the ID in the
           # [Metronome app](https://app.metronome.com/offering/pricing-units).
           credit_type_id: nil,
-          # A list of custom field filters for alert types that support advanced filtering.
-          # Only present for contract invoices.
+          # A list of custom field filters for threshold notification types that support
+          # advanced filtering. Only present for contract invoices.
           custom_field_filters: nil,
-          # If provided, will create this alert for this specific customer. To create an
-          # alert for all customers, do not specify a `customer_id`.
+          # If provided, will create this threshold notification for this specific customer.
+          # To create a notification for all customers, do not specify a `customer_id`.
           customer_id: nil,
-          # If true, the alert will evaluate immediately on customers that already meet the
-          # alert threshold. If false, it will only evaluate on future customers that
-          # trigger the alert threshold. Defaults to true.
+          # If true, the threshold notification will evaluate immediately on customers that
+          # already meet the notification threshold. If false, it will only evaluate on
+          # future customers that trigger the threshold. Defaults to true.
           evaluate_on_create: nil,
-          # Only present for `spend_threshold_reached` alerts. Scope alert to a specific
-          # group key on individual line items.
+          # Only present for `spend_threshold_reached` notifications. Scope notification to
+          # a specific group key on individual line items.
           group_values: nil,
-          # Only supported for invoice_total_reached alerts. A list of invoice types to
-          # evaluate.
+          # Only supported for invoice_total_reached threshold notifications. A list of
+          # invoice types to evaluate.
           invoice_types_filter: nil,
-          # If provided, will create this alert for this specific plan. To create an alert
-          # for all customers, do not specify a `plan_id`.
+          # If provided, will create this threshold notification for this specific plan. To
+          # create a notification for all customers, do not specify a `plan_id`.
           plan_id: nil,
           # Prevents the creation of duplicates. If a request to create a record is made
           # with a previously used uniqueness key, a new record will not be created and the
@@ -118,33 +120,34 @@ module MetronomeSDK
         )
         end
 
-        # Permanently disable an alert and remove it from active monitoring across all
-        # customers. Archived alerts stop evaluating immediately and can optionally
-        # release their uniqueness key for reuse in future alert configurations.
+        # Permanently disable a threshold notification and remove it from active
+        # monitoring across all customers. Archived threshold notifications stop
+        # evaluating immediately and can optionally release their uniqueness key for reuse
+        # in future threshold notification configurations.
         #
         # ### Use this endpoint to:
         #
-        # - Decommission alerts that are no longer needed
-        # - Clean up test or deprecated alert configurations
-        # - Free up uniqueness keys for reuse with new alerts
-        # - Stop alert evaluations without losing historical configuration data
+        # - Decommission threshold notifications that are no longer needed
+        # - Clean up test or deprecated threshold notification configurations
+        # - Free up uniqueness keys for reuse with new threshold notifications
+        # - Stop threshold notification evaluations without losing historical
+        #   configuration data
         # - Disable outdated monitoring rules during pricing model transitions
         #
         # ### Key response fields:
         #
-        # - data: Object containing the archived alert's ID
-        # - Alert evaluation stops immediately for all affected customers
-        # - Historical alert data and configurations remain accessible for audit purposes
+        # - data: Object containing the archived threshold notification's ID
         #
         # ### Usage guidelines:
         #
-        # - Irreversible for evaluation: Archived alerts cannot be re-enabled; create a
-        #   new alert to resume monitoring
+        # - Irreversible for evaluation: Archived threshold notifications cannot be
+        #   re-enabled; create a new threshold notification to resume monitoring
         # - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
-        #   key in future alerts
-        # - Immediate effect: Alert evaluation stops instantly across all customers
-        # - Historical preservation: Archive operation maintains alert history and
-        #   configuration for compliance and auditing
+        #   key in future threshold notifications
+        # - Immediate effect: Threshold notification evaluation stops instantly across all
+        #   customers
+        # - Historical preservation: Archive operation maintains threshold notification
+        #   history and configuration for compliance and auditing
         sig do
           params(
             id: String,
@@ -153,9 +156,10 @@ module MetronomeSDK
           ).returns(MetronomeSDK::Models::V1::AlertArchiveResponse)
         end
         def archive(
-          # The Metronome ID of the alert
+          # The Metronome ID of the threshold notification
           id:,
-          # If true, resets the uniqueness key on this alert so it can be re-used
+          # If true, resets the uniqueness key on this threshold notification so it can be
+          # re-used
           release_uniqueness_key: nil,
           request_options: {}
         )

data/rbi/metronome_sdk/resources/v1/contracts.rbi

@@ -389,7 +389,7 @@ module MetronomeSDK
 
         # Amendments will be replaced by Contract editing. New clients should implement
         # using the `editContract` endpoint. Read more about the migration to contract
-        # editing [here](https://docs.metronome.com/migrate-amendments-to-edits/) and
+        # editing [here](/guides/implement-metronome/migrate-amendments-to-edits/) and
         # reach out to your Metronome representative for more details. Once contract
         # editing is enabled, access to this endpoint will be removed.
         sig do
@@ -553,6 +553,7 @@ module MetronomeSDK
             id: String,
             covering_date: Time,
             effective_before: Time,
+            exclude_zero_balances: T::Boolean,
             include_archived: T::Boolean,
             include_balance: T::Boolean,
             include_contract_balances: T::Boolean,
@@ -574,6 +575,8 @@ module MetronomeSDK
           covering_date: nil,
           # Include only balances that have any access before the provided date (exclusive)
           effective_before: nil,
+          # Exclude balances with zero amounts from the response.
+          exclude_zero_balances: nil,
           # Include archived credits and credits from archived contracts.
           include_archived: nil,
           # Include the balance of credits and commits in the response. Setting this flag
@@ -736,11 +739,12 @@ module MetronomeSDK
         )
         end
 
-        # Update or and an end date to a contract. Ending a contract early will impact
+        # Update or add an end date to a contract. Ending a contract early will impact
         # draft usage statements, truncate any terms, and remove upcoming scheduled
         # invoices. Moving the date into the future will only extend the contract length.
-        # Terms and scheduled invoices are not extended. Use this if a contract's end date
-        # has changed or if a perpetual contract ends.
+        # Terms and scheduled invoices are not extended. In-advance subscriptions will not
+        # be extended. Use this if a contract's end date has changed or if a perpetual
+        # contract ends.
         sig do
           params(
             contract_id: String,

data/rbi/metronome_sdk/resources/v1/credit_grants.rbi

@@ -4,7 +4,8 @@ module MetronomeSDK
   module Resources
     class V1
       class CreditGrants
-        # Create a new credit grant
+        # Create a new credit grant. This is a Plans (deprecated) endpoint. New clients
+        # should implement using Contracts.
         sig do
           params(
             customer_id: String,
@@ -65,7 +66,8 @@ module MetronomeSDK
         )
         end
 
-        # List credit grants. This list does not included voided grants.
+        # List credit grants. This list does not included voided grants. This is a Plans
+        # (deprecated) endpoint. New clients should implement using Contracts.
         sig do
           params(
             limit: Integer,
@@ -105,7 +107,8 @@ module MetronomeSDK
         )
         end
 
-        # Edit an existing credit grant
+        # Edit an existing credit grant. This is a Plans (deprecated) endpoint. New
+        # clients should implement using Contracts.
         sig do
           params(
             id: String,
@@ -130,7 +133,8 @@ module MetronomeSDK
 
         # Fetches a list of credit ledger entries. Returns lists of ledgers per customer.
         # Ledger entries are returned in chronological order. Ledger entries associated
-        # with voided credit grants are not included.
+        # with voided credit grants are not included. This is a Plans (deprecated)
+        # endpoint. New clients should implement using Contracts.
         sig do
           params(
             next_page: String,
@@ -170,7 +174,8 @@ module MetronomeSDK
         )
         end
 
-        # Void a credit grant
+        # Void a credit grant. This is a Plans (deprecated) endpoint. New clients should
+        # implement using Contracts.
         sig do
           params(
             id: String,

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

@@ -5,17 +5,26 @@ module MetronomeSDK
     class V1
       class Customers
         class Alerts
-          # Retrieve the real-time evaluation status for a specific alert-customer pair.
-          # This endpoint provides instant visibility into whether a customer has triggered
-          # an alert condition, enabling you to monitor account health and take proactive
-          # action based on current alert states.
+          # Retrieve the real-time evaluation status for a specific threshold
+          # notification-customer pair. This endpoint provides instant visibility into
+          # whether a customer has triggered a threshold notification condition, enabling
+          # you to monitor account health and take proactive action based on current
+          # threshold notification states.
           #
           # ### Use this endpoint to:
           #
-          # - Check if a specific customer is currently violating an alert threshold
+          # - Check if a specific customer is currently violating an threshold notification
           #   (`in_alarm` status)
-          # - Verify alert configuration details and threshold values for a customer
-          # - Integrate alert status checks into customer support tools or admin interfaces
+          # - Verify threshold notification configuration details and threshold values for a
+          #   customer
+          # - Monitor the evaluation state of newly created or recently modified threshold
+          #   notification
+          # - Build dashboards or automated workflows that respond to specific threshold
+          #   notification conditions
+          # - Validate threshold notification behavior before deploying to production
+          #   customers
+          # - Integrate threshold notification status checks into customer support tools or
+          #   admin interfaces
           #
           # ### Key response fields:
           #
@@ -24,29 +33,32 @@ module MetronomeSDK
           # - `customer_status`: The current evaluation state
           #
           # - `ok` - Customer is within acceptable thresholds
-          # - `in_alarm`- Customer has breached the alert threshold
-          # - `evaluating` - Alert has yet to be evaluated (typically due to a customer or
-          #   alert having just been created)
-          # - `null` - Alert has been archived
-          # - `triggered_by`: Additional context about what caused the alert to trigger
-          #   (when applicable)
-          # - alert: Complete alert configuration including:
-          #   - Alert ID, name, and type
+          # - `in_alarm` - Customer has breached the threshold for the notification
+          # - `evaluating` - Notification is currently being evaluated (typically during
+          #   initial setup)
+          # - `null` - Notification has been archived
+          # - `triggered_by`: Additional context about what caused the notification to
+          #   trigger (when applicable)
+          # - alert: Complete threshold notification configuration including:
+          #   - Notification ID, name, and type
           #   - Current threshold values and credit type information
-          #   - Alert status (enabled, disabled, or archived)
+          #   - Notification status (enabled, disabled, or archived)
           #   - Last update timestamp
           #   - Any applied filters (credit grant types, custom fields, group values)
           #
           # ### Usage guidelines:
           #
           # - Customer status: Returns the current evaluation state, not historical data.
-          #   For alert history, use webhook notifications or event logs
-          # - Archived alerts: Returns null for customer_status if the alert has been
-          #   archived, but still includes the alert configuration details
-          # - Integration patterns: This endpoint can be used to check a customer's alert
-          #   status, but shouldn't be scraped. You should instead rely on the webhook
-          #   notification to understand when customers are moved to IN_ALARM.
-          # - Error handling: Returns 404 if either the customer or alert ID doesn't exist
+          #   For threshold notification history, use webhook notifications or event logs
+          # - Required parameters: Both customer_id and alert_id must be valid UUIDs that
+          #   exist in your organization
+          # - Archived notifications: Returns null for customer_status if the notification
+          #   has been archived, but still includes the notification configuration details
+          # - Performance considerations: This endpoint queries live evaluation state,
+          #   making it ideal for real-time monitoring but not for bulk status checks
+          # - Integration patterns: Best used for on-demand status checks in response to
+          #   user actions or as part of targeted monitoring workflows
+          # - Error handling: Returns 404 if either the customer or alert_id doesn't exist
           #   or isn't accessible to your organization
           sig do
             params(
@@ -64,45 +76,51 @@ module MetronomeSDK
             )
           end
           def retrieve(
-            # The Metronome ID of the alert
+            # The Metronome ID of the threshold notification
             alert_id:,
             # The Metronome ID of the customer
             customer_id:,
-            # Only present for `spend_threshold_reached` alerts. Retrieve the alert for a
-            # specific group key-value pair.
+            # Only present for `spend_threshold_reached` notifications. Retrieve the
+            # notification for a specific group key-value pair.
             group_values: nil,
-            # When parallel alerts are enabled during migration, this flag denotes whether to
-            # fetch alerts for plans or contracts.
+            # When parallel threshold notifications are enabled during migration, this flag
+            # denotes whether to fetch notifications for plans or contracts.
             plans_or_contracts: nil,
             request_options: {}
           )
           end
 
-          # Retrieve all alert configurations and their current statuses for a specific
-          # customer in a single API call. This endpoint provides a comprehensive view of
-          # all alerts monitoring a customer account.
+          # Retrieve all threshold notification configurations and their current statuses
+          # for a specific customer in a single API call. This endpoint provides a
+          # comprehensive view of all threshold notification monitoring a customer account.
           #
           # ### Use this endpoint to:
           #
-          # - Display all active alerts for a customer in dashboards or admin panels
-          # - Quickly identify which alerts a customer is currently triggering
-          # - Audit alert coverage for specific accounts
-          # - Filter alerts by status (enabled, disabled, or archived)
+          # - Display all active threshold notifications for a customer in dashboards or
+          #   admin panels
+          # - Quickly identify which threshold notifications a customer is currently
+          #   triggering
+          # - Audit threshold notification coverage for specific accounts
+          # - Filter threshold notifications by status (enabled, disabled, or archived)
           #
           # ### Key response fields:
           #
           # - data: Array of CustomerAlert objects, each containing:
           #   - Current evaluation status (`ok`, `in_alarm`, `evaluating`, or `null`)
-          #   - Complete alert configuration and threshold details
-          #   - Alert metadata including type, name, and last update time
-          # - `next_page`: Pagination cursor for retrieving additional results
+          #   - Complete threshold notification configuration and threshold details
+          #   - Threshold notification metadata including type, name, and last update time
+          # - next_page: Pagination cursor for retrieving additional results
           #
           # ### Usage guidelines:
           #
-          # - Default behavior: Returns only enabled alerts unless alert_statuses filter is
-          #   specified
+          # - Default behavior: Returns only enabled threshold notifications unless
+          #   `alert_statuses` filter is specified
           # - Pagination: Use the `next_page` cursor to retrieve all results for customers
-          #   with many alerts
+          #   with many notifications
+          # - Performance: Efficiently retrieves multiple threshold notification statuses in
+          #   a single request instead of making individual calls
+          # - Filtering: Pass the `alert_statuses` array to include disabled or archived
+          #   threshold notifications in results
           sig do
             params(
               customer_id: String,
@@ -123,30 +141,31 @@ module MetronomeSDK
             customer_id:,
             # Query param: Cursor that indicates where the next page of results should start.
             next_page: nil,
-            # Body param: Optionally filter by alert status. If absent, only enabled alerts
-            # will be returned.
+            # Body param: Optionally filter by threshold notification status. If absent, only
+            # enabled notifications will be returned.
             alert_statuses: nil,
             request_options: {}
           )
           end
 
-          # Force an immediate re-evaluation of a specific alert for a customer, clearing
-          # any previous state and triggering a fresh assessment against current thresholds.
-          # This endpoint ensures alert accuracy after configuration changes or data
-          # corrections.
+          # Force an immediate re-evaluation of a specific threshold notification for a
+          # customer, clearing any previous state and triggering a fresh assessment against
+          # current thresholds. This endpoint ensures threshold notification accuracy after
+          # configuration changes or data corrections.
           #
           # ### Use this endpoint to:
           #
-          # - Clear false positive alerts after fixing data issues
-          # - Re-evaluate alerts after adjusting customer balances or credits
-          # - Test alert behavior during development and debugging
-          # - Resolve stuck alerts that may be in an incorrect state
+          # - Clear false positive threshold notifications after fixing data issues
+          # - Re-evaluate threshold notifications after adjusting customer balances or
+          #   credits
+          # - Test threshold notification behavior during development and debugging
+          # - Resolve stuck threshold notification that may be in an incorrect state
           # - Trigger immediate evaluation after threshold modifications
           #
           # ### Key response fields:
           #
-          # - 200 Success: Confirmation that the alert has been reset and re-evaluation
-          #   initiated
+          # - 200 Success: Confirmation that the threshold notification has been reset and
+          #   re-evaluation initiated
           # - No response body is returned - the operation completes asynchronously
           #
           # ### Usage guidelines:
@@ -166,7 +185,7 @@ module MetronomeSDK
             ).void
           end
           def reset(
-            # The Metronome ID of the alert
+            # The Metronome ID of the threshold notification
             alert_id:,
             # The Metronome ID of the customer
             customer_id:,

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

@@ -5,7 +5,8 @@ module MetronomeSDK
     class V1
       class Customers
         class BillingConfig
-          # Set the billing configuration for a given customer.
+          # Set the billing configuration for a given customer. This is a Plans (deprecated)
+          # endpoint. New clients should implement using Contracts.
           sig do
             params(
               customer_id: String,
@@ -32,13 +33,15 @@ module MetronomeSDK
             aws_product_code: nil,
             # Body param:
             aws_region: nil,
-            # Body param:
+            # Body param: The collection method for the customer's invoices. NOTE:
+            # `auto_charge_payment_intent` and `manually_charge_payment_intent` are in beta.
             stripe_collection_method: nil,
             request_options: {}
           )
           end
 
-          # Fetch the billing configuration for the given customer.
+          # Fetch the billing configuration for the given customer. This is a Plans
+          # (deprecated) endpoint. New clients should implement using Contracts.
           sig do
             params(
               customer_id: String,
@@ -58,7 +61,8 @@ module MetronomeSDK
           end
 
           # Delete the billing configuration for a given customer. Note: this is unsupported
-          # for Azure and AWS Marketplace customers.
+          # for Azure and AWS Marketplace customers. This is a Plans (deprecated) endpoint.
+          # New clients should implement using Contracts.
           sig do
             params(
               customer_id: String,

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

@@ -34,7 +34,8 @@ module MetronomeSDK
           # #### Billing configuration:
           #
           # - invoice_contract_id is required for postpaid commits and for prepaid commits
-          #   with billing (only optional for free prepaid commits)
+          #   with billing (only optional for free prepaid commits) unless do_not_invoice is
+          #   set to true
           # - For postpaid commits: access_schedule and invoice_schedule must have matching
           #   amounts
           # - For postpaid commits: only one schedule item is allowed in both schedules.
@@ -123,7 +124,7 @@ module MetronomeSDK
             description: nil,
             # The contract that this commit will be billed on. This is required for "POSTPAID"
             # commits and for "PREPAID" commits unless there is no invoice schedule above
-            # (i.e., the commit is 'free').
+            # (i.e., the commit is 'free'), or if do_not_invoice is set to true.
             invoice_contract_id: nil,
             # Required for "POSTPAID" commits: the true up invoice will be generated at this
             # time and only one schedule item is allowed; the total must match

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

@@ -159,7 +159,8 @@ module MetronomeSDK
           )
           end
 
-          # 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.
           sig do
             params(
               customer_id: String,
@@ -287,6 +288,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/plans.rbi

@@ -5,7 +5,8 @@ module MetronomeSDK
     class V1
       class Customers
         class Plans
-          # 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.
           sig do
             params(
               customer_id: String,
@@ -31,7 +32,8 @@ module MetronomeSDK
 
           # 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.
           sig do
             params(
               customer_id: String,
@@ -82,7 +84,8 @@ module MetronomeSDK
           )
           end
 
-          # 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.
           sig do
             params(
               customer_id: String,
@@ -116,7 +119,8 @@ module MetronomeSDK
 
           # 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.
           sig do
             params(
               customer_id: String,