metronome-sdk 0.3.0 → 1.0.0

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

@@ -8,15 +8,58 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::AlertRetrieveParams} for more details.
           #
-          # Get the customer alert status and alert information for the specified customer
-          # and alert
-          #
-          # @overload retrieve(alert_id:, customer_id:, plans_or_contracts: nil, request_options: {})
+          # 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
+          #
+          # @overload retrieve(alert_id:, customer_id:, group_values: nil, plans_or_contracts: nil, request_options: {})
           #
           # @param alert_id [String] The Metronome ID of the alert
           #
           # @param customer_id [String] The Metronome ID of the customer
           #
+          # @param group_values [Array<MetronomeSDK::Models::V1::Customers::AlertRetrieveParams::GroupValue>] Only present for `spend_threshold_reached` alerts. Retrieve the alert for a spec
+          #
           # @param plans_or_contracts [Symbol, MetronomeSDK::Models::V1::Customers::AlertRetrieveParams::PlansOrContracts] When parallel alerts are enabled during migration, this flag denotes whether to
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
@@ -38,7 +81,31 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::AlertListParams} for more details.
           #
-          # 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
           #
           # @overload list(customer_id:, next_page: nil, alert_statuses: nil, request_options: {})
           #
@@ -50,7 +117,7 @@ module MetronomeSDK
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
           #
-          # @return [MetronomeSDK::Models::V1::Customers::AlertListResponse]
+          # @return [MetronomeSDK::Internal::CursorPageWithoutLimit<MetronomeSDK::Models::V1::Customers::CustomerAlert>]
           #
           # @see MetronomeSDK::Models::V1::Customers::AlertListParams
           def list(params)
@@ -61,12 +128,40 @@ module MetronomeSDK
               path: "v1/customer-alerts/list",
               query: parsed.slice(*query_params),
               body: parsed.except(*query_params),
-              model: MetronomeSDK::Models::V1::Customers::AlertListResponse,
+              page: MetronomeSDK::Internal::CursorPageWithoutLimit,
+              model: MetronomeSDK::V1::Customers::CustomerAlert,
               options: options
             )
           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
           #
           # @overload reset(alert_id:, customer_id:, request_options: {})
           #

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

@@ -8,7 +8,68 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::CommitCreateParams} for more details.
           #
-          # 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.
           #
           # @overload create(access_schedule:, customer_id:, priority:, product_id:, type:, applicable_contract_ids: nil, applicable_product_ids: nil, applicable_product_tags: nil, custom_fields: nil, description: nil, invoice_contract_id: nil, invoice_schedule: nil, name: nil, netsuite_sales_order_id: nil, rate_type: nil, salesforce_opportunity_id: nil, specifiers: nil, uniqueness_key: nil, request_options: {})
           #
@@ -28,7 +89,7 @@ module MetronomeSDK
           #
           # @param applicable_product_tags [Array<String>] Which tags the commit applies to. If applicable*product_ids, applicable_product*
           #
-          # @param custom_fields [Hash{Symbol=>String}]
+          # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           #
           # @param description [String] Used only in UI/API. It is not exposed to end customers.
           #
@@ -44,7 +105,7 @@ module MetronomeSDK
           #
           # @param salesforce_opportunity_id [String] This field's availability is dependent on your client's configuration.
           #
-          # @param specifiers [Array<MetronomeSDK::Models::V1::Customers::CommitCreateParams::Specifier>] List of filters that determine what kind of customer usage draws down a commit o
+          # @param specifiers [Array<MetronomeSDK::Models::CommitSpecifierInput>] List of filters that determine what kind of customer usage draws down a commit o
           #
           # @param uniqueness_key [String] Prevents the creation of duplicates. If a request to create a commit or credit i
           #
@@ -67,7 +128,49 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::CommitListParams} for more details.
           #
-          # 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
           #
           # @overload list(customer_id:, commit_id: nil, covering_date: nil, effective_before: nil, include_archived: nil, include_balance: nil, include_contract_commits: nil, include_ledgers: nil, limit: nil, next_page: nil, starting_at: nil, request_options: {})
           #
@@ -95,7 +198,7 @@ module MetronomeSDK
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
           #
-          # @return [MetronomeSDK::Models::V1::Customers::CommitListResponse]
+          # @return [MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::Commit>]
           #
           # @see MetronomeSDK::Models::V1::Customers::CommitListParams
           def list(params)
@@ -104,7 +207,8 @@ module MetronomeSDK
               method: :post,
               path: "v1/contracts/customerCommits/list",
               body: parsed,
-              model: MetronomeSDK::Models::V1::Customers::CommitListResponse,
+              page: MetronomeSDK::Internal::BodyCursorPage,
+              model: MetronomeSDK::Commit,
               options: options
             )
           end
@@ -113,9 +217,15 @@ module MetronomeSDK
           # {MetronomeSDK::Models::V1::Customers::CommitUpdateEndDateParams} for more
           # details.
           #
-          # 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.
           #
           # @overload update_end_date(commit_id:, customer_id:, access_ending_before: nil, invoices_ending_before: nil, request_options: {})
           #

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

@@ -8,7 +8,55 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::CreditCreateParams} for more details.
           #
-          # 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.
           #
           # @overload create(access_schedule:, customer_id:, priority:, product_id:, applicable_contract_ids: nil, applicable_product_ids: nil, applicable_product_tags: nil, custom_fields: nil, description: nil, name: nil, netsuite_sales_order_id: nil, rate_type: nil, salesforce_opportunity_id: nil, specifiers: nil, uniqueness_key: nil, request_options: {})
           #
@@ -26,7 +74,7 @@ module MetronomeSDK
           #
           # @param applicable_product_tags [Array<String>] Which tags the credit applies to. If both applicable*product_ids and applicable*
           #
-          # @param custom_fields [Hash{Symbol=>String}]
+          # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           #
           # @param description [String] Used only in UI/API. It is not exposed to end customers.
           #
@@ -38,7 +86,7 @@ module MetronomeSDK
           #
           # @param salesforce_opportunity_id [String] This field's availability is dependent on your client's configuration.
           #
-          # @param specifiers [Array<MetronomeSDK::Models::V1::Customers::CreditCreateParams::Specifier>] List of filters that determine what kind of customer usage draws down a commit o
+          # @param specifiers [Array<MetronomeSDK::Models::CommitSpecifierInput>] List of filters that determine what kind of customer usage draws down a commit o
           #
           # @param uniqueness_key [String] Prevents the creation of duplicates. If a request to create a commit or credit i
           #
@@ -61,7 +109,50 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Customers::CreditListParams} for more details.
           #
-          # 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
           #
           # @overload list(customer_id:, covering_date: nil, credit_id: nil, effective_before: nil, include_archived: nil, include_balance: nil, include_contract_credits: nil, include_ledgers: nil, limit: nil, next_page: nil, starting_at: nil, request_options: {})
           #
@@ -89,7 +180,7 @@ module MetronomeSDK
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
           #
-          # @return [MetronomeSDK::Models::V1::Customers::CreditListResponse]
+          # @return [MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::Credit>]
           #
           # @see MetronomeSDK::Models::V1::Customers::CreditListParams
           def list(params)
@@ -98,7 +189,8 @@ module MetronomeSDK
               method: :post,
               path: "v1/contracts/customerCredits/list",
               body: parsed,
-              model: MetronomeSDK::Models::V1::Customers::CreditListResponse,
+              page: MetronomeSDK::Internal::BodyCursorPage,
+              model: MetronomeSDK::Credit,
               options: options
             )
           end
@@ -107,8 +199,12 @@ module MetronomeSDK
           # {MetronomeSDK::Models::V1::Customers::CreditUpdateEndDateParams} for more
           # details.
           #
-          # 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.
           #
           # @overload update_end_date(access_ending_before:, credit_id:, customer_id:, request_options: {})
           #

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

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