metronome-sdk 0.3.0 → 2.0.0

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

@@ -24,7 +24,39 @@ module MetronomeSDK
           end
           attr_reader :named_schedules
 
-          # Create a new rate card
+          # In Metronome, the rate card is the central location for your pricing. Rate cards
+          # were built with new product launches and pricing changes in mind - you can
+          # update your products and pricing in one place, and that change will be
+          # automatically propagated across your customer cohorts. Most clients need only
+          # maintain one or a few rate cards within Metronome.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Create a rate card with a name and description
+          # - Define the rate card's single underlying fiat currency, and any number of
+          #   conversion rates between that fiat currency and custom pricing units. You can
+          #   then add products and associated rates in the fiat currency or custom pricing
+          #   unit for which you have defined a conversion rate.
+          # - Set aliases for the rate card. Aliases are human-readable names that you can
+          #   use in the place of the id of the rate card when provisioning a customer's
+          #   contract. By using an alias, you can easily create a contract and provision a
+          #   customer by choosing the paygo rate card, without storing the rate card id in
+          #   your internal systems. This is helpful when launching a new rate card for
+          #   paygo customers, you can update the alias for paygo to be scheduled to be
+          #   assigned to the new rate card without updating your code.
+          #
+          # ### Key response fields:
+          #
+          # - The ID of the rate card you just created
+          #
+          # ### Usage guidelines:
+          #
+          # - After creating a rate card, you can now use the addRate or addRates endpoints
+          #   to add products and their prices to it
+          # - A rate card alias can only be used by one rate card at a time. If you create a
+          #   contract with a rate card alias that is already in use by another rate card,
+          #   the original rate card's alias schedule will be updated. The alias will
+          #   reference the rate card to which it was most recently assigned.
           sig do
             params(
               name: String,
@@ -53,6 +85,7 @@ module MetronomeSDK
             aliases: nil,
             # Required when using custom pricing units in rates.
             credit_type_conversions: nil,
+            # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
             custom_fields: nil,
             description: nil,
             # The Metronome ID of the credit type to associate with the rate card, defaults to
@@ -62,8 +95,9 @@ module MetronomeSDK
           )
           end
 
-          # Get a specific rate card NOTE: Use `/contract-pricing/rate-cards/getRates` to
-          # retrieve rate card rates.
+          # Return details for a specific rate card including name, description, and
+          # aliases. This endpoint does not return rates - use the dedicated getRates or
+          # getRateSchedule endpoints to understand the rates on a rate card.
           sig do
             params(
               id: String,
@@ -75,7 +109,58 @@ module MetronomeSDK
           def retrieve(id:, request_options: {})
           end
 
-          # Update a rate card
+          # Update the metadata properties of an existing rate card, including its name,
+          # description, and aliases. This endpoint is designed for managing rate card
+          # identity and reference aliases rather than modifying pricing rates.
+          #
+          # Modifies the descriptive properties and alias configuration of a rate card
+          # without affecting the underlying pricing rates or schedules. This allows you to
+          # update how a rate card is identified and referenced throughout your system.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Rate card renaming: Update display names or descriptions for organizational
+          #   clarity
+          # - Alias management: Add, modify, or schedule alias transitions for seamless rate
+          #   card migrations
+          # - Documentation updates: Keep rate card descriptions current with business
+          #   context
+          # - Self-serve provisioning setup: Configure aliases to enable code-free rate card
+          #   transitions
+          #
+          # #### Active contract impact:
+          #
+          # - Alias changes: Already-created contracts continue using their originally
+          #   assigned rate cards.
+          # - Other changes made using this endpoint will only impact the Metronome UI.
+          #
+          # #### Grandfathering existing PLG customer pricing:
+          #
+          # - Rate card aliases support scheduled transitions, enabling seamless rate card
+          #   migrations for new customers, allowing existing customers to be grandfathered
+          #   into their existing prices without code. Note that there are multiple
+          #   mechanisms to support grandfathering in Metronome.
+          #
+          # #### How scheduled aliases work for PLG grandfathering:
+          #
+          # Initial setup:
+          #
+          # - Add alias to current rate card: Assign a stable alias (e.g.,
+          #   "standard-pricing") to your active rate card
+          # - Reference alias during contract creation: Configure your self-serve workflow
+          #   to create contracts using `rate_card_alias` instead of direct `rate_card_id`
+          # - Automatic resolution: New contracts referencing the alias automatically
+          #   resolve to the rate card associated with the alias at the point in time of
+          #   provisioning
+          #
+          # #### Grandfathering process:
+          #
+          # - Create new rate card: Build your new rate card with updated pricing structure
+          # - Schedule alias transition: Add the same alias to the new rate card with a
+          #   `starting_at` timestamp
+          # - Automatic cutover: Starting at the scheduled time, new contracts created in
+          #   your PLG workflow using that alias will automatically reference the new rate
+          #   card
           sig do
             params(
               rate_card_id: String,
@@ -104,8 +189,9 @@ module MetronomeSDK
           )
           end
 
-          # List rate cards NOTE: Use `/contract-pricing/rate-cards/getRates` to retrieve
-          # rate card rates.
+          # List all rate cards. Returns rate card IDs, names, descriptions, aliases, and
+          # other details. To view the rates associated with a given rate card, use the
+          # getRates or getRateSchedule endpoints.
           sig do
             params(
               limit: Integer,
@@ -129,7 +215,11 @@ module MetronomeSDK
           )
           end
 
-          # Archive a rate card
+          # Permanently disable a rate card by archiving it, preventing use in new contracts
+          # while preserving existing contract pricing. Use this when retiring old pricing
+          # models, consolidating rate cards, or removing outdated pricing structures.
+          # Returns the archived rate card ID and stops the rate card from appearing in
+          # contract creation workflows.
           sig do
             params(
               id: String,
@@ -141,8 +231,18 @@ module MetronomeSDK
           def archive(id:, request_options: {})
           end
 
-          # Get all rates for a rate card from starting_at (either in perpetuity or until
-          # ending_before, if provided)
+          # A rate card defines the prices that you charge for your products. Rate cards
+          # support scheduled changes over time, to allow you to easily roll out pricing
+          # changes and new product launches across your customer base. Use this endpoint to
+          # understand the rate schedule `starting_at` a given date, optionally filtering
+          # the list of rates returned based on product id or pricing group values. For
+          # example, you may want to display a schedule of upcoming price changes for a
+          # given product in your product experience - use this endpoint to fetch that
+          # information from its source of truth in Metronome.
+          #
+          # If you want to understand the rates for a specific customer's contract,
+          # inclusive of contract-level overrides, use the `getContractRateSchedule`
+          # endpoint.
           sig do
             params(
               rate_card_id: String,

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

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

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

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