metronome-sdk 0.2.0 → 1.0.0

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,

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

@@ -5,7 +5,46 @@ module MetronomeSDK
     class V1
       class Customers
         class Invoices
-          # 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
           sig do
             params(
               customer_id: String,
@@ -28,8 +67,52 @@ module MetronomeSDK
           )
           end
 
-          # 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
           sig do
             params(
               customer_id: String,
@@ -113,11 +196,44 @@ module MetronomeSDK
           )
           end
 
-          # List daily or hourly invoice breakdowns for a given customer, optionally
-          # filtered by status, date range, and/or credit type. Important considerations:
+          # 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:
           #
-          # - 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.
+          # - 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
           sig do
             params(
               customer_id: String,