metronome-sdk 0.3.0 → 2.0.0

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,69 @@ 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 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 threshold notification
+          #   (`in_alarm` status)
+          # - 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:
+          #
+          # A CustomerAlert object containing:
+          #
+          # - `customer_status`: The current evaluation state
+          #
+          # - `ok` - Customer is within acceptable thresholds
+          # - `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
+          #   - 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 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(
               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
@@ -19,18 +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:,
-            # When parallel alerts are enabled during migration, this flag denotes whether to
-            # fetch alerts for plans or contracts.
+            # Only present for `spend_threshold_reached` notifications. Retrieve the
+            # notification for a specific group key-value pair.
+            group_values: nil,
+            # 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
 
-          # Fetch all customer alert statuses and alert information for a customer
+          # 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 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 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 threshold notifications unless
+          #   `alert_statuses` filter is specified
+          # - Pagination: Use the `next_page` cursor to retrieve all results for customers
+          #   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,
@@ -40,21 +130,53 @@ 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
             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
 
-          # Reset state for an alert by customer id and force re-evaluation
+          # 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 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 threshold notification 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,
@@ -63,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/commits.rbi

@@ -5,7 +5,68 @@ module MetronomeSDK
     class V1
       class Customers
         class Commits
-          # Create a new commit at the customer level.
+          # Creates customer-level commits that establish spending commitments for customers
+          # across their Metronome usage. Commits represent contracted spending obligations
+          # that can be either prepaid (paid upfront) or postpaid (billed later).
+          #
+          # Note: In most cases, you should add commitments directly to customer contracts
+          # using the contract/create or contract/edit APIs.
+          #
+          # ### Use this endpoint to:
+          #
+          # Use this endpoint when you need to establish customer-level spending commitments
+          # that can be applied across multiple contracts or scoped to specific contracts.
+          # Customer-level commits are ideal for:
+          #
+          # - Enterprise-wide minimum spending agreements that span multiple contracts
+          # - Multi-contract volume commitments with shared spending pools
+          # - Cross-contract discount tiers based on aggregate usage
+          #
+          # #### Commit type Requirements:
+          #
+          # - You must specify either "prepaid" or "postpaid" as the commit type:
+          # - Prepaid commits: Customer pays upfront; invoice_schedule is optional (if
+          #   omitted, creates a commit without an invoice)
+          # - Postpaid commits: Customer pays when the commitment expires (the end of the
+          #   access_schedule); invoice_schedule is required and must match access_schedule
+          #   totals.
+          #
+          # #### Billing configuration:
+          #
+          # - invoice_contract_id is required for postpaid commits and for prepaid commits
+          #   with billing (only optional for free prepaid commits)
+          # - For postpaid commits: access_schedule and invoice_schedule must have matching
+          #   amounts
+          # - For postpaid commits: only one schedule item is allowed in both schedules.
+          #
+          # #### Scoping flexibility:
+          #
+          # Customer-level commits can be configured in a few ways:
+          #
+          # - Contract-specific: Use the `applicable_contract_ids` field to limit the commit
+          #   to specific contracts
+          # - Cross-contract: Leave `applicable_contract_ids` empty to allow the commit to
+          #   be used across all of the customer's contracts
+          #
+          # #### Product targeting:
+          #
+          # Commits can be scoped to specific products using applicable_product_ids,
+          # applicable_product_tags, or specifiers, or left unrestricted to apply to all
+          # products.
+          #
+          # #### Priority considerations:
+          #
+          # When multiple commits are applicable, the one with the lower priority value will
+          # be consumed first. If there is a tie, contract level commits and credits will be
+          # applied before customer level commits and credits. Plan your priority scheme
+          # carefully to ensure commits are applied in the desired order.
+          #
+          # ### Usage guidelines:
+          #
+          # ⚠️ Preferred Alternative: In most cases, you should add commits directly to
+          # contracts using the create contract or edit contract APIs instead of creating
+          # customer-level commits. Contract-level commits provide better organization and
+          # are the recommended approach for standard use cases.
           sig do
             params(
               access_schedule:
@@ -28,10 +89,7 @@ module MetronomeSDK
               rate_type:
                 MetronomeSDK::V1::Customers::CommitCreateParams::RateType::OrSymbol,
               salesforce_opportunity_id: String,
-              specifiers:
-                T::Array[
-                  MetronomeSDK::V1::Customers::CommitCreateParams::Specifier::OrHash
-                ],
+              specifiers: T::Array[MetronomeSDK::CommitSpecifierInput::OrHash],
               uniqueness_key: String,
               request_options: MetronomeSDK::RequestOptions::OrHash
             ).returns(MetronomeSDK::Models::V1::Customers::CommitCreateResponse)
@@ -59,6 +117,7 @@ module MetronomeSDK
             # applicable_product_tags or specifiers are not provided, the commit applies to
             # all products.
             applicable_product_tags: nil,
+            # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
             custom_fields: nil,
             # Used only in UI/API. It is not exposed to end customers.
             description: nil,
@@ -92,7 +151,49 @@ module MetronomeSDK
           )
           end
 
-          # List commits.
+          # Retrieve all commit agreements for a customer, including both prepaid and
+          # postpaid commitments. This endpoint provides comprehensive visibility into
+          # contractual spending obligations, enabling you to track commitment utilization
+          # and manage customer contracts effectively.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Display commitment balances and utilization in customer dashboards
+          # - Track prepaid commitment drawdown and remaining balances
+          # - Monitor postpaid commitment progress toward minimum thresholds
+          # - Build commitment tracking and forecasting tools
+          # - Show commitment history with optional ledger details
+          # - Manage rollover balances between contract periods
+          #
+          # ### Key response fields:
+          #
+          # An array of Commit objects containing:
+          #
+          # - Commit type: PREPAID (pay upfront) or POSTPAID (pay at true-up)
+          # - Rate type: COMMIT_RATE (discounted) or LIST_RATE (standard pricing)
+          # - Access schedule: When commitment funds become available
+          # - Invoice schedule: When the customer is billed
+          # - Product targeting: Which product(s) usage is eligible to draw from this commit
+          # - Optional ledger entries: Transaction history (if `include_ledgers=true`)
+          # - Balance information: Current available amount (if `include_balance=true`)
+          # - Rollover settings: Fraction of unused amount that carries forward
+          #
+          # ### Usage guidelines:
+          #
+          # - Pagination: Results limited to 25 commits per page; use 'next_page' for more
+          # - Date filtering options:
+          #   - `covering_date`: Commits active on a specific date
+          #   - `starting_at`: Commits with access on/after a date
+          #   - `effective_before`: Commits with access before a date (exclusive)
+          # - Scope options:
+          #   - `include_contract_commits`: Include contract-level commits (not just
+          #     customer-level)
+          #   - `include_archived`: Include archived commits and commits from archived
+          #     contracts
+          # - Performance considerations:
+          #   - include_ledgers: Adds detailed transaction history (slower)
+          #   - include_balance: Adds current balance calculation (slower)
+          # - Optional filtering: Use commit_id to retrieve a specific commit
           sig do
             params(
               customer_id: String,
@@ -107,7 +208,9 @@ module MetronomeSDK
               next_page: String,
               starting_at: Time,
               request_options: MetronomeSDK::RequestOptions::OrHash
-            ).returns(MetronomeSDK::Models::V1::Customers::CommitListResponse)
+            ).returns(
+              MetronomeSDK::Internal::BodyCursorPage[MetronomeSDK::Commit]
+            )
           end
           def list(
             customer_id:,
@@ -136,9 +239,15 @@ module MetronomeSDK
           )
           end
 
-          # Pull forward the end date of a prepaid commit. Use the "edit a commit" endpoint
-          # to extend the end date of a prepaid commit, or to make other edits to the
-          # commit.
+          # Shortens the end date of a prepaid commit to terminate it earlier than
+          # originally scheduled. Use this endpoint when you need to cancel or reduce the
+          # duration of an existing prepaid commit. Only works with prepaid commit types and
+          # can only move the end date forward (earlier), not extend it.
+          #
+          # ### Usage guidelines:
+          #
+          # To extend commit end dates or make other comprehensive edits, use the 'edit
+          # commit' endpoint instead.
           sig do
             params(
               commit_id: String,

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

@@ -5,7 +5,55 @@ module MetronomeSDK
     class V1
       class Customers
         class Credits
-          # Create a new credit at the customer level.
+          # Creates customer-level credits that provide spending allowances or free credit
+          # balances for customers across their Metronome usage. Note: In most cases, you
+          # should add credits directly to customer contracts using the contract/create or
+          # contract/edit APIs.
+          #
+          # ### Use this endpoint to:
+          #
+          # Use this endpoint when you need to provision credits directly at the customer
+          # level that can be applied across multiple contracts or scoped to specific
+          # contracts. Customer-level credits are ideal for:
+          #
+          # - Customer onboarding incentives that apply globally
+          # - Flexible spending allowances that aren't tied to a single contract
+          # - Migration scenarios where you need to preserve existing customer balances
+          #
+          # #### Scoping flexibility:
+          #
+          # Customer-level credits can be configured in two ways:
+          #
+          # - Contract-specific: Use the applicable_contract_ids field to limit the credit
+          #   to specific contracts
+          # - Cross-contract: Leave applicable_contract_ids empty to allow the credit to be
+          #   used across all of the customer's contracts
+          #
+          # #### Product Targeting:
+          #
+          # Credits can be scoped to specific products using `applicable_product_ids` or
+          # `applicable_product_tags`, or left unrestricted to apply to all products.
+          #
+          # #### Priority considerations:
+          #
+          # When multiple credits are applicable, the one with the lower priority value will
+          # be consumed first. If there is a tie, contract level commits and credits will be
+          # applied before customer level commits and credits. Plan your priority scheme
+          # carefully to ensure credits are applied in the desired order.
+          #
+          # #### Access Schedule Required:
+          #
+          # You must provide an `access_schedule` that defines when and how much credit
+          # becomes available to the customer over time. This usually is aligned to the
+          # contract schedule or starts immediately and is set to expire in the future.
+          #
+          # ### Usage Guidelines:
+          #
+          # ⚠️ Preferred Alternative: In most cases, you should add credits directly to
+          # contracts using the contract/create or contract/edit APIs instead of creating
+          # customer-level credits. Contract-level credits provide better organization, and
+          # are easier for finance teams to recognize revenue, and are the recommended
+          # approach for most use cases.
           sig do
             params(
               access_schedule:
@@ -23,10 +71,7 @@ module MetronomeSDK
               rate_type:
                 MetronomeSDK::V1::Customers::CreditCreateParams::RateType::OrSymbol,
               salesforce_opportunity_id: String,
-              specifiers:
-                T::Array[
-                  MetronomeSDK::V1::Customers::CreditCreateParams::Specifier::OrHash
-                ],
+              specifiers: T::Array[MetronomeSDK::CommitSpecifierInput::OrHash],
               uniqueness_key: String,
               request_options: MetronomeSDK::RequestOptions::OrHash
             ).returns(MetronomeSDK::Models::V1::Customers::CreditCreateResponse)
@@ -48,6 +93,7 @@ module MetronomeSDK
             # Which tags the credit applies to. If both applicable_product_ids and
             # applicable_product_tags are not provided, the credit applies to all products.
             applicable_product_tags: nil,
+            # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
             custom_fields: nil,
             # Used only in UI/API. It is not exposed to end customers.
             description: nil,
@@ -72,7 +118,50 @@ module MetronomeSDK
           )
           end
 
-          # List credits.
+          # Retrieve a detailed list of all credits available to a customer, including
+          # promotional credits and contract-specific credits. This endpoint provides
+          # comprehensive visibility into credit balances, access schedules, and usage
+          # rules, enabling you to build credit management interfaces and track available
+          # funding.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Display all available credits in customer billing dashboards
+          # - Show credit balances and expiration dates
+          # - Track credit usage history with optional ledger details
+          # - Build credit management and reporting tools
+          # - Monitor promotional credit utilization • Support customer inquiries about
+          #   available credits
+          #
+          # ### Key response fields:
+          #
+          # An array of Credit objects containing:
+          #
+          # - Credit details: Name, priority, and which applicable products/tags it applies
+          #   to
+          # - Product ID: The `product_id` of the credit. This is for external mapping into
+          #   your quote-to-cash stack, not the product it applies to.
+          # - Access schedule: When credits become available and expire
+          # - Optional ledger entries: Transaction history (if `include_ledgers=true`)
+          # - Balance information: Current available amount (if `include_balance=true`)
+          # - Metadata: Custom fields and usage specifiers
+          #
+          # ### Usage guidelines:
+          #
+          # - Pagination: Results limited to 25 commits per page; use next_page for more
+          # - Date filtering options:
+          #   - `covering_date`: Credits active on a specific date
+          #   - `starting_at`: Credits with access on/after a date
+          #   - `effective_before`: Credits with access before a date (exclusive)
+          # - Scope options:
+          #   - `include_contract_credits`: Include contract-level credits (not just
+          #     customer-level)
+          #   - `include_archived`: Include archived credits and credits from archived
+          #     contracts
+          # - Performance considerations:
+          #   - `include_ledgers`: Adds detailed transaction history (slower)
+          #   - `include_balance`: Adds current balance calculation (slower)
+          # - Optional filtering: Use credit_id to retrieve a specific commit
           sig do
             params(
               customer_id: String,
@@ -87,7 +176,9 @@ module MetronomeSDK
               next_page: String,
               starting_at: Time,
               request_options: MetronomeSDK::RequestOptions::OrHash
-            ).returns(MetronomeSDK::Models::V1::Customers::CreditListResponse)
+            ).returns(
+              MetronomeSDK::Internal::BodyCursorPage[MetronomeSDK::Credit]
+            )
           end
           def list(
             customer_id:,
@@ -116,8 +207,12 @@ module MetronomeSDK
           )
           end
 
-          # Pull forward the end date of a credit. Use the "edit a credit" endpoint to
-          # extend the end date of a credit, or to make other edits to the credit.
+          # Shortens the end date of an existing customer credit to terminate it earlier
+          # than originally scheduled. Only allows moving end dates forward (earlier), not
+          # extending them.
+          #
+          # Note: To extend credit end dates or make comprehensive edits, use the 'edit
+          # credit' endpoint instead.
           sig do
             params(
               access_ending_before: Time,