metronome-sdk 0.2.0 → 1.0.0

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

@@ -13,7 +13,129 @@ module MetronomeSDK
         sig { returns(MetronomeSDK::Resources::V1::Contracts::NamedSchedules) }
         attr_reader :named_schedules
 
-        # Create a new contract
+        # Contracts define a customer's products, pricing, discounts, access duration, and
+        # billing configuration. Contracts serve as the central billing agreement for both
+        # PLG and Enterprise customers, you can automatically customers access to your
+        # products and services directly from your product or CRM.
+        #
+        # ### Use this endpoint to:
+        #
+        # - PLG onboarding: Automatically provision new self-serve customers with
+        #   contracts when they sign up.
+        # - Enterprise sales: Push negotiated contracts from Salesforce with custom
+        #   pricing and commitments
+        # - Promotional pricing: Implement time-limited discounts and free trials through
+        #   overrides
+        #
+        # ### Key components:
+        #
+        # #### Contract Term and Billing Schedule
+        #
+        # - Set contract duration using `starting_at` and `ending_before` fields. PLG
+        #   contracts typically use perpetual agreements (no end date), while Enterprise
+        #   contracts have fixed end dates which can be edited over time in the case of
+        #   co-term upsells.
+        #
+        # #### Rate Card
+        #
+        # If you are offering usage based pricing, you can set a rate card for the
+        # contract to reference through `rate_card_id` or `rate_card_alias`. The rate card
+        # is a store of all of your usage based products and their centralized pricing.
+        # Any new products or price changes on the rate card can be set to automatically
+        # propagate to all associated contracts - this ensures consistent pricing and
+        # product launches flow to contracts without manual updates and migrations. The
+        # `usage_statement_schedule` determines the cadence on which Metronome will
+        # finalize a usage invoice for the customer. This defaults to monthly on the 1st,
+        # with options for custom dates, quarterly, or annual cadences. Note: Most usage
+        # based billing companies align usage statements to be evaluated aligned to the
+        # first of the month. Read more about
+        # [Rate Cards](https://docs.metronome.com/pricing-packaging/create-manage-rate-cards/).
+        #
+        # #### Overrides and discounts
+        #
+        # Customize pricing on the contract through time-bounded overrides that can target
+        # specific products, product families, or complex usage scenarios. Overrides
+        # enable two key capabilities:
+        #
+        # - Discounts: Apply percentage discounts, fixed rate reductions, or
+        #   quantity-based pricing tiers
+        # - Entitlements: Provide special pricing or access to specific products for
+        #   negotiated deals
+        #
+        # Read more about
+        # [Contract Overrides](https://docs.metronome.com/manage-product-access/add-contract-override/).
+        #
+        # #### Commits and Credits
+        #
+        # Using commits, configure prepaid or postpaid spending commitments where
+        # customers promise to spend a certain amount over the contract period paid in
+        # advance or in arrears. Use credits to provide free spending allowances. Under
+        # the hood these are the same mechanisms, however, credits are typically offered
+        # for free (SLA or promotional) or as a part of an allotment associated with a
+        # Subscription.
+        #
+        # In Metronome, you can set commits and credits to only be applicable for a subset
+        # of usage. Use `applicable_product_ids` or `applicable_product_tags` to create
+        # product or product-family specific commits or credits, or you can build complex
+        # boolean logic specifiers to target usage based on pricing and presentation group
+        # values using `override_specifiers`.
+        #
+        # These objects can also also be configured to have a recurrence schedule to
+        # easily model customer packaging which includes recurring monthly or quarterly
+        # allotments.
+        #
+        # Commits support rollover settings (`rollover_fraction`) to transfer unused
+        # balances between contract periods, either entirely or as a percentage.
+        #
+        # Read more about
+        # [Credits and Commits](https://docs.metronome.com/pricing-packaging/apply-credits-commits/).
+        #
+        # #### Subscriptions
+        #
+        # You can add a fixed recurring charge to a contract, like monthly licenses or
+        # seat-based fees, using the subscription charge. Subscription charges are defined
+        # on your rate card and you can select which subscription is applicable to add to
+        # each contract. When you add a subscription to a contract you need to:
+        #
+        # - Define whether the subscription is paid for in-advance or in-arrears
+        #   (`collection_schedule`)
+        # - Define the proration behavior (`proration`)
+        # - Specify an initial quantity (`initial_quantity`)
+        # - Define which subscription rate on the rate card should be used
+        #   (`subscription_rate`)
+        #
+        # Read more about
+        # [Subscriptions](https://docs.metronome.com/manage-product-access/create-subscription/).
+        #
+        # #### Scheduled Charges
+        #
+        # Set up one-time, recurring, or entirely custom charges that occur on specific
+        # dates, separate from usage-based billing or commitments. These can be used to
+        # model non-recurring platform charges or professional services.
+        #
+        # #### Threshold Billing
+        #
+        # Metronome allows you to configure automatic billing triggers when customers
+        # reach spending thresholds to prevent fraud and manage risk. You can use
+        # `spend_threshold_configuration` to trigger an invoice to cover current charges
+        # whenever the threshold is reached or you can ensure the customer maintains a
+        # minimum prepaid balance using the `prepaid_balance_configuration`.
+        #
+        # Read more about
+        # [Spend Threshold](https://docs.metronome.com/manage-product-access/spend-thresholds/)
+        # and
+        # [Prepaid Balance Thresholds](https://docs.metronome.com/manage-product-access/prepaid-balance-thresholds/).
+        #
+        # ### Usage guidelines:
+        #
+        # - You can always
+        #   [Edit Contracts](https://docs.metronome.com/manage-product-access/edit-contract/)
+        #   after it has been created, using the `editContract` endpoint. Metronome keeps
+        #   track of all edits, both in the audit log and over the `getEditHistory`
+        #   endpoint.
+        # - Customers in Metronome can have multiple concurrent contracts at one time. Use
+        #   `usage_filters` to route the correct usage to each contract.
+        #   [Read more about usage filters](https://docs.metronome.com/manage-product-access/provision-customer/#create-a-usage-filter).
         sig do
           params(
             customer_id: String,
@@ -42,7 +164,7 @@ module MetronomeSDK
                 MetronomeSDK::V1::ContractCreateParams::Override::OrHash
               ],
             prepaid_balance_threshold_configuration:
-              MetronomeSDK::V1::ContractCreateParams::PrepaidBalanceThresholdConfiguration::OrHash,
+              MetronomeSDK::PrepaidBalanceThresholdConfiguration::OrHash,
             priority: Float,
             professional_services:
               T::Array[
@@ -70,7 +192,7 @@ module MetronomeSDK
             scheduled_charges_on_usage_invoices:
               MetronomeSDK::V1::ContractCreateParams::ScheduledChargesOnUsageInvoices::OrSymbol,
             spend_threshold_configuration:
-              MetronomeSDK::V1::ContractCreateParams::SpendThresholdConfiguration::OrHash,
+              MetronomeSDK::SpendThresholdConfiguration::OrHash,
             subscriptions:
               T::Array[
                 MetronomeSDK::V1::ContractCreateParams::Subscription::OrHash
@@ -94,6 +216,7 @@ module MetronomeSDK
           billing_provider_configuration: nil,
           commits: nil,
           credits: nil,
+          # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           custom_fields: nil,
           # This field's availability is dependent on your client's configuration.
           discounts: nil,
@@ -174,8 +297,13 @@ module MetronomeSDK
         )
         end
 
-        # This is the v1 endpoint to list all contracts for a customer. New clients should
-        # implement using the v2 endpoint.
+        # Retrieves all contracts for a specific customer, including pricing, terms,
+        # credits, and commitments. Use this to view a customer's contract history and
+        # current agreements for billing management. Returns contract details with
+        # optional ledgers and balance information.
+        #
+        # ⚠️ Note: This is the legacy v1 endpoint - new integrations should use the v2
+        # endpoint for enhanced features.
         sig do
           params(
             customer_id: String,
@@ -209,7 +337,24 @@ module MetronomeSDK
         )
         end
 
-        # Add a manual balance entry
+        # Manually adjust the available balance on a commit or credit. This entry is
+        # appended to the commit ledger as a new event. Optionally include a description
+        # that provides the reasoning for the entry.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Address incorrect usage burn-down caused by malformed usage or invalid config
+        # - Decrease available balance to account for outages where usage may have not
+        #   been tracked or sent to Metronome
+        # - Issue credits to customers in the form of increased balance on existing commit
+        #   or credit
+        #
+        # ### Usage guidelines:
+        #
+        # Manual ledger entries can be extremely useful for resolving discrepancies in
+        # Metronome. However, most corrections to inaccurate billings can be modified
+        # upstream of the commit, whether that is via contract editing, rate editing, or
+        # other actions that cause an invoice to be recalculated.
         sig do
           params(
             id: String,
@@ -243,7 +388,7 @@ module MetronomeSDK
         end
 
         # Amendments will be replaced by Contract editing. New clients should implement
-        # using the editContract endpoint. Read more about the migration to contract
+        # using the `editContract` endpoint. Read more about the migration to contract
         # editing [here](https://docs.metronome.com/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.
@@ -288,6 +433,7 @@ module MetronomeSDK
           starting_at:,
           commits: nil,
           credits: nil,
+          # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           custom_fields: nil,
           # This field's availability is dependent on your client's configuration.
           discounts: nil,
@@ -307,7 +453,26 @@ module MetronomeSDK
         )
         end
 
-        # Archive a contract
+        # Permanently end and archive a contract along with all its terms. Any draft
+        # invoices will be canceled, and all upcoming scheduled invoices will be
+        # voided–also all finalized invoices can optionally be voided. Use this in the
+        # event a contract was incorrectly created and needed to be removed from a
+        # customer.
+        #
+        # #### Impact on commits and credits:
+        #
+        # When archiving a contract, all associated commits and credits are also archived.
+        # For prepaid commits with active segments, Metronome automatically generates
+        # expiration ledger entries to close out any remaining balances, ensuring accurate
+        # accounting of unused prepaid amounts. These ledger entries will appear in the
+        # commit's transaction history with type `PREPAID_COMMIT_EXPIRATION`.
+        #
+        # #### Archived contract visibility:
+        #
+        # Archived contracts remain accessible for historical reporting and audit
+        # purposes. They can be retrieved using the `ListContracts` endpoint by setting
+        # the `include_archived` parameter to `true` or in the Metronome UI when the "Show
+        # archived" option is enabled.
         sig do
           params(
             contract_id: String,
@@ -328,7 +493,11 @@ module MetronomeSDK
         )
         end
 
-        # Creates historical usage invoices for a contract
+        # Create historical usage invoices for past billing periods on specific contracts.
+        # Use this endpoint to generate retroactive invoices with custom usage line items,
+        # quantities, and date ranges. Supports preview mode to validate invoice data
+        # before creation. Ideal for billing migrations or correcting past billing
+        # periods.
         sig do
           params(
             invoices:
@@ -344,7 +513,40 @@ module MetronomeSDK
         def create_historical_invoices(invoices:, preview:, request_options: {})
         end
 
-        # List balances (commits and credits).
+        # Retrieve a comprehensive view of all available balances (commits and credits)
+        # for a customer. This endpoint provides real-time visibility into prepaid funds,
+        # postpaid commitments, promotional credits, and other balance types that can
+        # offset usage charges, helping you build transparent billing experiences.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Display current available balances in customer dashboards
+        # - Verify available funds before approving high-usage operations
+        # - Generate balance reports for finance teams
+        # - Filter balances by contract or date ranges
+        #
+        # ### Key response fields:
+        #
+        # An array of balance objects (all credits and commits) containing:
+        #
+        # - Balance details: Current available amount for each commit or credit
+        # - Metadata: Product associations, priorities, applicable date ranges
+        # - Optional ledger entries: Detailed transaction history (if
+        #   `include_ledgers=true`)
+        # - Balance calculations: Including pending transactions and future-dated entries
+        # - Custom fields: Any additional metadata attached to balances
+        #
+        # ### Usage guidelines:
+        #
+        # - Date filtering: Use `effective_before` to include only balances with access
+        #   before a specific date (exclusive)
+        # - Set `include_balance=true` for calculated balance amounts on each commit or
+        #   credit
+        # - Set `include_ledgers=true` for full transaction history
+        # - Set `include_contract_balances = true` to see contract level balances
+        # - Balance logic: Reflects currently accessible amounts, excluding expired/future
+        #   segments
+        # - Manual adjustments: Includes all manual ledger entries, even future-dated ones
         sig do
           params(
             customer_id: String,
@@ -359,7 +561,11 @@ module MetronomeSDK
             next_page: String,
             starting_at: Time,
             request_options: MetronomeSDK::RequestOptions::OrHash
-          ).returns(MetronomeSDK::Models::V1::ContractListBalancesResponse)
+          ).returns(
+            MetronomeSDK::Internal::BodyCursorPage[
+              MetronomeSDK::Models::V1::ContractListBalancesResponse::Variants
+            ]
+          )
         end
         def list_balances(
           customer_id:,
@@ -388,7 +594,13 @@ module MetronomeSDK
         )
         end
 
-        # Get the rate schedule for the rate card on a given contract.
+        # For a specific customer and contract, get the rates at a specific point in time.
+        # This endpoint takes the contract's rate card into consideration, including
+        # scheduled changes. It also takes into account overrides on the contract.
+        #
+        # For example, if you want to show your customer a summary of the prices they are
+        # paying, inclusive of any negotiated discounts or promotions, use this endpoint.
+        # This endpoint only returns rates that are entitled.
         sig do
           params(
             contract_id: String,
@@ -425,8 +637,16 @@ module MetronomeSDK
         )
         end
 
-        # Fetch the quantity and price for a subscription over time. End-point does not
-        # return future scheduled changes.
+        # Get the history of subscription quantities and prices over time for a given
+        # `subscription_id`. This endpoint can be used to power an in-product experience
+        # where you show a customer their historical changes to seat count. Future changes
+        # are not included in this endpoint - use the `getContract` endpoint to view the
+        # future scheduled changes to a subscription's quantity.
+        #
+        # Subscriptions are used to model fixed recurring fees as well as seat-based
+        # recurring fees. To model changes to the number of seats in Metronome, you can
+        # increment or decrement the quantity on a subscription at any point in the past
+        # or future.
         sig do
           params(
             contract_id: String,
@@ -478,7 +698,24 @@ module MetronomeSDK
         )
         end
 
-        # Set usage filter for a contract
+        # If a customer has multiple contracts with overlapping rates, the usage filter
+        # routes usage to the appropriate contract based on a predefined group key.
+        #
+        # As an example, imagine you have a customer associated with two projects. Each
+        # project is associated with its own contract. You can create a usage filter with
+        # group key `project_id` on each contract, and route usage for `project_1` to the
+        # first contract and `project_2` to the second contract.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Support enterprise contracting scenarios where multiple contracts are
+        #   associated to the same customer with the same rates.
+        # - Update the usage filter associated with the contract over time.
+        #
+        # ### Usage guidelines:
+        #
+        # To use usage filters, the `group_key` must be defined on the billable metrics
+        # underlying the rate card on the contracts.
         sig do
           params(
             contract_id: String,
@@ -499,7 +736,11 @@ module MetronomeSDK
         )
         end
 
-        # Update the end date of a contract
+        # Update or and 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.
         sig do
           params(
             contract_id: String,

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

@@ -141,7 +141,11 @@ module MetronomeSDK
             ending_before: Time,
             starting_on: Time,
             request_options: MetronomeSDK::RequestOptions::OrHash
-          ).returns(MetronomeSDK::Models::V1::CreditGrantListEntriesResponse)
+          ).returns(
+            MetronomeSDK::Internal::CursorPageWithoutLimit[
+              MetronomeSDK::Models::V1::CreditGrantListEntriesResponse
+            ]
+          )
         end
         def list_entries(
           # Query param: Cursor that indicates where the next page of results should start.

data/rbi/metronome_sdk/resources/v1/custom_fields.rbi

@@ -4,8 +4,35 @@ module MetronomeSDK
   module Resources
     class V1
       class CustomFields
-        # Add a key to the allow list for a given entity. There is a 100 character limit
-        # on custom field keys.
+        # Creates a new custom field key for a given entity (e.g. billable metric,
+        # contract, alert).
+        #
+        # Custom fields are properties that you can add to Metronome objects to store
+        # metadata like foreign keys or other descriptors. This metadata can get
+        # transferred to or accessed by other systems to contextualize Metronome data and
+        # power business processes. For example, to service workflows like revenue
+        # recognition, reconciliation, and invoicing, custom fields help Metronome know
+        # the relationship between entities in the platform and third-party systems.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Create a new custom field key for Customer objects in Metronome. You can then
+        #   use the Set Custom Field Values endpoint to set the value of this key for a
+        #   specific customer.
+        # - Specify whether the key should enforce uniqueness. If the key is set to
+        #   enforce uniqueness and you attempt to set a custom field value for the key
+        #   that already exists, it will fail.
+        #
+        # ### Usage guidelines:
+        #
+        # - Custom fields set on commits, credits, and contracts can be used to scope
+        #   alert evaluation. For example, you can create a spend threshold alert that
+        #   only considers spend associated with contracts with custom field key
+        #   `contract_type` and value `paygo`
+        # - Custom fields set on products can be used in the Stripe integration to set
+        #   metadata on invoices.
+        # - Custom fields for customers, contracts, invoices, products, commits, scheduled
+        #   charges, and subscriptions are passed down to the invoice.
         sig do
           params(
             enforce_uniqueness: T::Boolean,
@@ -17,7 +44,10 @@ module MetronomeSDK
         def add_key(enforce_uniqueness:, entity:, key:, request_options: {})
         end
 
-        # Deletes one or more custom fields on an instance of a Metronome entity.
+        # Remove specific custom field values from a Metronome entity instance by
+        # specifying the field keys to delete. Use this endpoint to clean up unwanted
+        # custom field data while preserving other fields on the same entity. Requires the
+        # entity type, entity ID, and array of keys to remove.
         sig do
           params(
             entity:
@@ -30,7 +60,10 @@ module MetronomeSDK
         def delete_values(entity:, entity_id:, keys:, request_options: {})
         end
 
-        # List all active custom field keys, optionally filtered by entity type.
+        # Retrieve all your active custom field keys, with optional filtering by entity
+        # type (customer, contract, product, etc.). Use this endpoint to discover what
+        # custom field keys are available before setting values on entities or to audit
+        # your custom field configuration across different entity types.
         sig do
           params(
             next_page: String,
@@ -39,7 +72,11 @@ module MetronomeSDK
                 MetronomeSDK::V1::CustomFieldListKeysParams::Entity::OrSymbol
               ],
             request_options: MetronomeSDK::RequestOptions::OrHash
-          ).returns(MetronomeSDK::Models::V1::CustomFieldListKeysResponse)
+          ).returns(
+            MetronomeSDK::Internal::CursorPageWithoutLimit[
+              MetronomeSDK::Models::V1::CustomFieldListKeysResponse
+            ]
+          )
         end
         def list_keys(
           # Query param: Cursor that indicates where the next page of results should start.
@@ -50,7 +87,10 @@ module MetronomeSDK
         )
         end
 
-        # Remove a key from the allow list for a given entity.
+        # Removes a custom field key from the allowlist for a specific entity type,
+        # preventing future use of that key across all instances of the entity. Existing
+        # values for this key on entity instances will no longer be accessible once the
+        # key is removed.
         sig do
           params(
             entity:
@@ -62,13 +102,10 @@ module MetronomeSDK
         def remove_key(entity:, key:, request_options: {})
         end
 
-        # Sets one or more custom fields on an instance of a Metronome entity. If a
-        # key/value pair passed in this request matches one already set on the entity, its
-        # value will be overwritten. Any key/value pairs that exist on the entity that do
-        # not match those passed in this request will remain untouched. This endpoint is
-        # transactional and will update all key/value pairs or no key/value pairs. Partial
-        # updates are not supported. There is a 200 character limit on custom field
-        # values.
+        # Sets custom field values on a specific Metronome entity instance. Overwrites
+        # existing values for matching keys while preserving other fields. All updates are
+        # transactional—either all values are set or none are. Custom field values are
+        # limited to 200 characters each.
         sig do
           params(
             custom_fields: T::Hash[Symbol, String],
@@ -78,7 +115,13 @@ module MetronomeSDK
             request_options: MetronomeSDK::RequestOptions::OrHash
           ).void
         end
-        def set_values(custom_fields:, entity:, entity_id:, request_options: {})
+        def set_values(
+          # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+          custom_fields:,
+          entity:,
+          entity_id:,
+          request_options: {}
+        )
         end
 
         # @api private

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

@@ -5,12 +5,57 @@ module MetronomeSDK
     class V1
       class Customers
         class Alerts
-          # Get the customer alert status and alert information for the specified customer
-          # and alert
+          # 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.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Check if a specific customer is currently violating an alert threshold
+          #   (`in_alarm` status)
+          # - Verify alert configuration details and threshold values for a customer
+          # - Integrate alert status checks into customer support tools or admin interfaces
+          #
+          # ### Key response fields:
+          #
+          # A CustomerAlert object containing:
+          #
+          # - `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
+          #   - Current threshold values and credit type information
+          #   - Alert 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
+          #   or isn't accessible to your organization
           sig do
             params(
               alert_id: String,
               customer_id: String,
+              group_values:
+                T::Array[
+                  MetronomeSDK::V1::Customers::AlertRetrieveParams::GroupValue::OrHash
+                ],
               plans_or_contracts:
                 MetronomeSDK::V1::Customers::AlertRetrieveParams::PlansOrContracts::OrSymbol,
               request_options: MetronomeSDK::RequestOptions::OrHash
@@ -23,6 +68,9 @@ module MetronomeSDK
             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.
+            group_values: nil,
             # When parallel alerts are enabled during migration, this flag denotes whether to
             # fetch alerts for plans or contracts.
             plans_or_contracts: nil,
@@ -30,7 +78,31 @@ module MetronomeSDK
           )
           end
 
-          # Fetch all customer alert statuses and alert information for a customer
+          # 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.
+          #
+          # ### 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)
+          #
+          # ### 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
+          #
+          # ### Usage guidelines:
+          #
+          # - Default behavior: Returns only enabled alerts unless alert_statuses filter is
+          #   specified
+          # - Pagination: Use the `next_page` cursor to retrieve all results for customers
+          #   with many alerts
           sig do
             params(
               customer_id: String,
@@ -40,7 +112,11 @@ module MetronomeSDK
                   MetronomeSDK::V1::Customers::AlertListParams::AlertStatus::OrSymbol
                 ],
               request_options: MetronomeSDK::RequestOptions::OrHash
-            ).returns(MetronomeSDK::Models::V1::Customers::AlertListResponse)
+            ).returns(
+              MetronomeSDK::Internal::CursorPageWithoutLimit[
+                MetronomeSDK::V1::Customers::CustomerAlert
+              ]
+            )
           end
           def list(
             # Body param: The Metronome ID of the customer
@@ -54,7 +130,34 @@ module MetronomeSDK
           )
           end
 
-          # Reset state for an alert by customer id and force re-evaluation
+          # 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.
+          #
+          # ### 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
+          # - Trigger immediate evaluation after threshold modifications
+          #
+          # ### Key response fields:
+          #
+          # - 200 Success: Confirmation that the alert has been reset and re-evaluation
+          #   initiated
+          # - No response body is returned - the operation completes asynchronously
+          #
+          # ### Usage guidelines:
+          #
+          # - Immediate effect: Triggers re-evaluation instantly, which may result in new
+          #   webhook notifications if thresholds are breached
+          # - State clearing: Removes any cached evaluation state, ensuring a fresh
+          #   assessment
+          # - Use sparingly: Intended for exceptional cases, not routine operations
+          # - Asynchronous processing: The reset completes immediately, but re-evaluation
+          #   happens in the background
           sig do
             params(
               alert_id: String,