metronome-sdk 0.3.0 → 2.0.0

data/lib/metronome_sdk/models.rb

@@ -39,10 +39,24 @@ module MetronomeSDK
     mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
   end
 
+  BaseThresholdCommit = MetronomeSDK::Models::BaseThresholdCommit
+
   BaseUsageFilter = MetronomeSDK::Models::BaseUsageFilter
 
   Commit = MetronomeSDK::Models::Commit
 
+  CommitHierarchyConfiguration = MetronomeSDK::Models::CommitHierarchyConfiguration
+
+  CommitRate = MetronomeSDK::Models::CommitRate
+
+  CommitSpecifier = MetronomeSDK::Models::CommitSpecifier
+
+  CommitSpecifierInput = MetronomeSDK::Models::CommitSpecifierInput
+
+  Contract = MetronomeSDK::Models::Contract
+
+  ContractV2 = MetronomeSDK::Models::ContractV2
+
   ContractWithoutAmendments = MetronomeSDK::Models::ContractWithoutAmendments
 
   Credit = MetronomeSDK::Models::Credit
@@ -53,24 +67,48 @@ module MetronomeSDK
 
   EventTypeFilter = MetronomeSDK::Models::EventTypeFilter
 
+  HierarchyConfiguration = MetronomeSDK::Models::HierarchyConfiguration
+
   ID = MetronomeSDK::Models::ID
 
   Override = MetronomeSDK::Models::Override
 
+  OverrideTier = MetronomeSDK::Models::OverrideTier
+
+  OverwriteRate = MetronomeSDK::Models::OverwriteRate
+
+  PaymentGateConfig = MetronomeSDK::Models::PaymentGateConfig
+
+  PaymentGateConfigV2 = MetronomeSDK::Models::PaymentGateConfigV2
+
+  PrepaidBalanceThresholdConfiguration = MetronomeSDK::Models::PrepaidBalanceThresholdConfiguration
+
+  PrepaidBalanceThresholdConfigurationV2 = MetronomeSDK::Models::PrepaidBalanceThresholdConfigurationV2
+
   PropertyFilter = MetronomeSDK::Models::PropertyFilter
 
   ProService = MetronomeSDK::Models::ProService
 
   Rate = MetronomeSDK::Models::Rate
 
+  RecurringCommitSubscriptionConfig = MetronomeSDK::Models::RecurringCommitSubscriptionConfig
+
   ScheduledCharge = MetronomeSDK::Models::ScheduledCharge
 
   ScheduleDuration = MetronomeSDK::Models::ScheduleDuration
 
   SchedulePointInTime = MetronomeSDK::Models::SchedulePointInTime
 
+  SpendThresholdConfiguration = MetronomeSDK::Models::SpendThresholdConfiguration
+
+  SpendThresholdConfigurationV2 = MetronomeSDK::Models::SpendThresholdConfigurationV2
+
+  Subscription = MetronomeSDK::Models::Subscription
+
   Tier = MetronomeSDK::Models::Tier
 
+  UpdateBaseThresholdCommit = MetronomeSDK::Models::UpdateBaseThresholdCommit
+
   V1 = MetronomeSDK::Models::V1
 
   V2 = MetronomeSDK::Models::V2

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

@@ -7,33 +7,77 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::AlertCreateParams} for more details.
         #
-        # Create a new alert
+        # Create a new threshold notification to monitor customer spending, balances, and
+        # billing metrics in real-time. Metronome's notification system provides
+        # industry-leading speed with immediate evaluation capabilities, enabling you to
+        # proactively manage customer accounts and prevent revenue leakage.
+        #
+        # This endpoint creates configurable threshold notifications that continuously
+        # monitor various billing thresholds including spend limits, credit balances,
+        # commitment utilization, and invoice totals. Threshold notifications can be
+        # configured globally for all customers or targeted to specific customer accounts.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Proactively monitor customer spending patterns to prevent unexpected overages
+        #   or credit exhaustion
+        # - Automate notifications when customers approach commitment limits or credit
+        #   thresholds
+        # - Enable real-time intervention for accounts at risk of churn or payment issues
+        # - Scale billing operations by automating threshold-based workflows and
+        #   notifications
+        #
+        # ### Key response fields:
+        #
+        # A successful response returns a CustomerAlert object containing:
+        #
+        # - The threshold notification configuration with its unique ID and current status
+        # - The customer's evaluation status (ok, in_alarm, or evaluating)
+        # - Threshold notification metadata including type, threshold values, and update
+        #   timestamps
+        #
+        # ### Usage guidelines:
+        #
+        # - Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant
+        #   evaluation against existing customers
+        # - Uniqueness constraints: Each threshold notification must have a unique
+        #   `uniqueness_key` within your organization. Use `release_uniqueness_key` :
+        #   `true` when archiving to reuse keys
+        # - Notification type requirements: Different threshold notification types require
+        #   specific fields (e.g., `billable_metric_id` for usage notifications,
+        #   `credit_type_id` for credit-based threshold notifications)
+        # - Webhook delivery: Threshold notifications trigger webhook notifications for
+        #   real-time integration with your systems. Configure webhook endpoints before
+        #   creating threshold notifications
+        # - Performance at scale: Metronome's event-driven architecture processes
+        #   threshold notification evaluations in real-time as usage events stream in,
+        #   unlike competitors who rely on periodic polling or batch evaluation cycles
         #
         # @overload create(alert_type:, name:, threshold:, billable_metric_id: nil, credit_grant_type_filters: nil, credit_type_id: nil, custom_field_filters: nil, customer_id: nil, evaluate_on_create: nil, group_values: nil, invoice_types_filter: nil, plan_id: nil, uniqueness_key: nil, request_options: {})
         #
-        # @param alert_type [Symbol, MetronomeSDK::Models::V1::AlertCreateParams::AlertType] Type of the alert
+        # @param alert_type [Symbol, MetronomeSDK::Models::V1::AlertCreateParams::AlertType] Type of the threshold notification
         #
-        # @param name [String] Name of the alert
+        # @param name [String] Name of the threshold notification
         #
-        # @param threshold [Float] Threshold value of the alert policy. Depending upon the alert type, this number
+        # @param threshold [Float] Threshold value of the notification policy. Depending upon the notification typ
         #
-        # @param billable_metric_id [String] For alerts of type `usage_threshold_reached`, specifies which billable metric to
+        # @param billable_metric_id [String] For threshold notifications of type `usage_threshold_reached`, specifies which b
         #
-        # @param credit_grant_type_filters [Array<String>] An array of strings, representing a way to filter the credit grant this alert ap
+        # @param credit_grant_type_filters [Array<String>] An array of strings, representing a way to filter the credit grant this threshol
         #
-        # @param credit_type_id [String] ID of the credit's currency, defaults to USD. If the specific alert type require
+        # @param credit_type_id [String] ID of the credit's currency, defaults to USD. If the specific notification type
         #
-        # @param custom_field_filters [Array<MetronomeSDK::Models::V1::AlertCreateParams::CustomFieldFilter>] A list of custom field filters for alert types that support advanced filtering.
+        # @param custom_field_filters [Array<MetronomeSDK::Models::V1::AlertCreateParams::CustomFieldFilter>] A list of custom field filters for threshold notification types that support adv
         #
-        # @param customer_id [String] If provided, will create this alert for this specific customer. To create an ale
+        # @param customer_id [String] If provided, will create this threshold notification for this specific customer.
         #
-        # @param evaluate_on_create [Boolean] If true, the alert will evaluate immediately on customers that already meet the
+        # @param evaluate_on_create [Boolean] If true, the threshold notification will evaluate immediately on customers that
         #
-        # @param group_values [Array<MetronomeSDK::Models::V1::AlertCreateParams::GroupValue>] Only present for `spend_threshold_reached` alerts. Scope alert to a specific gro
+        # @param group_values [Array<MetronomeSDK::Models::V1::AlertCreateParams::GroupValue>] Only present for `spend_threshold_reached` notifications. Scope notification to
         #
-        # @param invoice_types_filter [Array<String>] Only supported for invoice_total_reached alerts. A list of invoice types to eval
+        # @param invoice_types_filter [Array<String>] Only supported for invoice_total_reached threshold notifications. A list of invo
         #
-        # @param plan_id [String] If provided, will create this alert for this specific plan. To create an alert f
+        # @param plan_id [String] If provided, will create this threshold notification for this specific plan. To
         #
         # @param uniqueness_key [String] Prevents the creation of duplicates. If a request to create a record is made wit
         #
@@ -53,13 +97,43 @@ module MetronomeSDK
           )
         end
 
-        # Archive an existing alert
+        # Some parameter documentations has been truncated, see
+        # {MetronomeSDK::Models::V1::AlertArchiveParams} for more details.
+        #
+        # Permanently disable a threshold notification and remove it from active
+        # monitoring across all customers. Archived threshold notifications stop
+        # evaluating immediately and can optionally release their uniqueness key for reuse
+        # in future threshold notification configurations.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Decommission threshold notifications that are no longer needed
+        # - Clean up test or deprecated threshold notification configurations
+        # - Free up uniqueness keys for reuse with new threshold notifications
+        # - Stop threshold notification evaluations without losing historical
+        #   configuration data
+        # - Disable outdated monitoring rules during pricing model transitions
+        #
+        # ### Key response fields:
+        #
+        # - data: Object containing the archived threshold notification's ID
+        #
+        # ### Usage guidelines:
+        #
+        # - Irreversible for evaluation: Archived threshold notifications cannot be
+        #   re-enabled; create a new threshold notification to resume monitoring
+        # - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
+        #   key in future threshold notifications
+        # - Immediate effect: Threshold notification evaluation stops instantly across all
+        #   customers
+        # - Historical preservation: Archive operation maintains threshold notification
+        #   history and configuration for compliance and auditing
         #
         # @overload archive(id:, release_uniqueness_key: nil, request_options: {})
         #
-        # @param id [String] The Metronome ID of the alert
+        # @param id [String] The Metronome ID of the threshold notification
         #
-        # @param release_uniqueness_key [Boolean] If true, resets the uniqueness key on this alert so it can be re-used
+        # @param release_uniqueness_key [Boolean] If true, resets the uniqueness key on this threshold notification so it can be r
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/metronome_sdk/resources/v1/audit_logs.rb

@@ -7,10 +7,45 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::AuditLogListParams} for more details.
         #
-        # Retrieves a range of audit logs. If no further audit logs are currently
-        # available, the data array will be empty. As new audit logs are created,
-        # subsequent requests using the same next_page value will be in the returned data
-        # array, ensuring a continuous and uninterrupted reading of audit logs.
+        # Get a comprehensive audit trail of all operations performed in your Metronome
+        # account, whether initiated through the API, web interface, or automated
+        # processes. This endpoint provides detailed logs of who did what and when,
+        # enabling compliance reporting, security monitoring, and operational
+        # troubleshooting across all interaction channels.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Monitor all account activity for security and compliance purposes
+        # - Track configuration changes regardless of source (API, UI, or system)
+        # - Investigate issues by reviewing historical operations
+        #
+        # ### Key response fields:
+        #
+        # An array of AuditLog objects containing:
+        #
+        # - id: Unique identifier for the audit log entry
+        # - timestamp: When the action occurred (RFC 3339 format)
+        # - actor: Information about who performed the action
+        # - request: Details including request ID, IP address, and user agent
+        # - `resource_type`: The type of resource affected (e.g., customer, contract,
+        #   invoice)
+        # - `resource_id`: The specific resource identifier
+        # - `action`: The operation performed
+        # - `next_page`: Cursor for continuous log retrieval
+        #
+        # ### Usage guidelines:
+        #
+        # - Continuous retrieval: The next_page token enables uninterrupted log
+        #   streaming—save it between requests to ensure no logs are missed
+        # - Empty responses: An empty data array means no new logs yet; continue polling
+        #   with the same next_page token
+        # - Date filtering:
+        #   - `starting_on`: Earliest logs to return (inclusive)
+        #   - `ending_before`: Latest logs to return (exclusive)
+        #   - Cannot be used with `next_page`
+        # - Resource filtering: Must specify both `resource_type` and `resource_id`
+        #   together
+        # - Sort order: Default is `date_asc`; use `date_desc` for newest first
         #
         # @overload list(ending_before: nil, limit: nil, next_page: nil, resource_id: nil, resource_type: nil, sort: nil, starting_on: nil, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/billable_metrics.rb

@@ -7,7 +7,35 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::BillableMetricCreateParams} for more details.
         #
-        # Creates a new Billable Metric.
+        # Create billable metrics programmatically with this endpoint—an essential step in
+        # configuring your pricing and packaging in Metronome.
+        #
+        # A billable metric is a customizable query that filters and aggregates events
+        # from your event stream. These metrics are continuously tracked as usage data
+        # enters Metronome through the ingestion pipeline. The ingestion process
+        # transforms raw usage data into actionable pricing metrics, enabling accurate
+        # metering and billing for your products.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Create individual or multiple billable metrics as part of a setup workflow.
+        # - Automate the entire pricing configuration process, from metric creation to
+        #   customer contract setup.
+        # - Define metrics using either standard filtering/aggregation or a custom SQL
+        #   query.
+        #
+        # ### Key response fields:
+        #
+        # - The ID of the billable metric that was created
+        # - The created billable metric will be available to be used in Products, usage
+        #   endpoints, and alerts.
+        #
+        # ### Usage guidelines:
+        #
+        # - Metrics defined using standard filtering and aggregation are Streaming
+        #   billable metrics, which have been optimized for ultra low latency and high
+        #   throughput workflows.
+        # - Use SQL billable metrics if you require more flexible aggregation options.
         #
         # @overload create(name:, aggregation_key: nil, aggregation_type: nil, custom_fields: nil, event_type_filter: nil, group_keys: nil, property_filters: nil, sql: nil, request_options: {})
         #
@@ -43,7 +71,17 @@ module MetronomeSDK
           )
         end
 
-        # Get a billable metric.
+        # Retrieves the complete configuration for a specific billable metric by its ID.
+        # Use this to review billable metric setup before associating it with products.
+        # Returns the metric's `name`, `event_type_filter`, `property_filters`,
+        # `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and
+        # `SQL query` (if it's a SQL billable metric).
+        #
+        # Important:
+        #
+        # - Archived billable metrics will include an `archived_at` timestamp; they no
+        #   longer process new usage events but remain accessible for historical
+        #   reference.
         #
         # @overload retrieve(billable_metric_id:, request_options: {})
         #
@@ -67,7 +105,11 @@ module MetronomeSDK
           )
         end
 
-        # List all billable metrics.
+        # Retrieves all billable metrics with their complete configurations. Use this for
+        # programmatic discovery and management of billable metrics, such as associating
+        # metrics to products and auditing for orphaned or archived metrics. Important:
+        # Archived metrics are excluded by default; use `include_archived`=`true`
+        # parameter to include them.
         #
         # @overload list(include_archived: nil, limit: nil, next_page: nil, request_options: {})
         #
@@ -94,7 +136,15 @@ module MetronomeSDK
           )
         end
 
-        # Archive an existing billable metric.
+        # Use this endpoint to retire billable metrics that are no longer used. After a
+        # billable metric is archived, that billable metric can no longer be used in any
+        # new Products to define how that product should be metered. If you archive a
+        # billable metric that is already associated with a Product, the Product will
+        # continue to function as usual, metering based on the definition of the archived
+        # billable metric.
+        #
+        # Archived billable metrics will be returned on the `getBillableMetric` and
+        # `listBillableMetrics` endpoints with a populated `archived_at` field.
         #
         # @overload archive(id:, request_options: {})
         #

data/lib/metronome_sdk/resources/v1/contracts/products.rb

@@ -8,7 +8,11 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Contracts::ProductCreateParams} for more details.
           #
-          # Create a new product
+          # Create a new product object. Products in Metronome represent your company's
+          # individual product or service offerings. A Product can be thought of as the
+          # basic unit of a line item on the invoice. This is analogous to SKUs or items in
+          # an ERP system. Give the product a meaningful name as they will appear on
+          # customer invoices.
           #
           # @overload create(name:, type:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, custom_fields: nil, exclude_free_usage: nil, is_refundable: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, tags: nil, request_options: {})
           #
@@ -22,7 +26,7 @@ module MetronomeSDK
           #
           # @param composite_tags [Array<String>] Required for COMPOSITE products
           #
-          # @param custom_fields [Hash{Symbol=>String}]
+          # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
           #
           # @param exclude_free_usage [Boolean] Beta feature only available for composite products. If true, products with $0 wi
           #
@@ -58,7 +62,7 @@ module MetronomeSDK
             )
           end
 
-          # Get a specific product
+          # Retrieve a product by its ID, including all metadata and historical changes.
           #
           # @overload retrieve(id:, request_options: {})
           #
@@ -82,7 +86,17 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Contracts::ProductUpdateParams} for more details.
           #
-          # Update a product
+          # Updates a product's configuration while maintaining billing continuity for
+          # active customers. Use this endpoint to modify product names, metrics, pricing
+          # rules, and composite settings without disrupting ongoing billing cycles. Changes
+          # are scheduled using the starting_at timestamp, which must be on an hour
+          # boundary—set future dates to schedule updates ahead of time, or past dates for
+          # retroactive changes. Returns the updated product ID upon success.
+          #
+          # ### Usage guidance:
+          #
+          # - Product type cannot be changed after creation. For incorrect product types,
+          #   create a new product and archive the original instead.
           #
           # @overload update(product_id:, starting_at:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, exclude_free_usage: nil, is_refundable: nil, name: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, tags: nil, request_options: {})
           #
@@ -135,7 +149,9 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Contracts::ProductListParams} for more details.
           #
-          # List products
+          # Get a paginated list of all products in your organization with their complete
+          # configuration, version history, and metadata. By default excludes archived
+          # products unless explicitly requested via the `archive_filter` parameter.
           #
           # @overload list(limit: nil, next_page: nil, archive_filter: nil, request_options: {})
           #
@@ -164,7 +180,10 @@ module MetronomeSDK
             )
           end
 
-          # Archive a product
+          # Archive a product. Any current rate cards associated with this product will
+          # continue to function as normal. However, it will no longer be available as an
+          # option for newly created rates. Once you archive a product, you can still
+          # retrieve it in the UI and API, but you cannot unarchive it.
           #
           # @overload archive(product_id:, request_options: {})
           #

data/lib/metronome_sdk/resources/v1/contracts/rate_cards/product_orders.rb

@@ -6,7 +6,10 @@ module MetronomeSDK
       class Contracts
         class RateCards
           class ProductOrders
-            # Updates ordering of specified products
+            # The ordering of products on a rate card determines the order in which the
+            # products will appear on customers' invoices. Use this endpoint to set the order
+            # of specific products on the rate card by moving them relative to their current
+            # location.
             #
             # @overload update(product_moves:, rate_card_id:, request_options: {})
             #
@@ -30,7 +33,9 @@ module MetronomeSDK
               )
             end
 
-            # Sets the ordering of products within a rate card
+            # The ordering of products on a rate card determines the order in which the
+            # products will appear on customers' invoices. Use this endpoint to set the order
+            # of products on the rate card.
             #
             # @overload set(product_order:, rate_card_id:, request_options: {})
             #

data/lib/metronome_sdk/resources/v1/contracts/rate_cards/rates.rb

@@ -10,7 +10,15 @@ module MetronomeSDK
             # {MetronomeSDK::Models::V1::Contracts::RateCards::RateListParams} for more
             # details.
             #
-            # Get all rates for a rate card at a point in time
+            # Understand the rate schedule at a given timestamp, optionally filtering the list
+            # of rates returned based on properties such as `product_id` and
+            # `pricing_group_values`. For example, you may want to display the current price
+            # 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.
             #
             # @overload list(at:, rate_card_id:, limit: nil, next_page: nil, selectors: nil, request_options: {})
             #
@@ -63,7 +71,7 @@ module MetronomeSDK
             #
             # @param billing_frequency [Symbol, MetronomeSDK::Models::V1::Contracts::RateCards::RateAddParams::BillingFrequency] Optional. Frequency to bill subscriptions with. Required for subscription type p
             #
-            # @param commit_rate [MetronomeSDK::Models::V1::Contracts::RateCards::RateAddParams::CommitRate] A distinct rate on the rate card. You can choose to use this rate rather than li
+            # @param commit_rate [MetronomeSDK::Models::CommitRate] A distinct rate on the rate card. You can choose to use this rate rather than li
             #
             # @param credit_type_id [String] The Metronome ID of the credit type to associate with price, defaults to USD (ce
             #

data/lib/metronome_sdk/resources/v1/contracts/rate_cards.rb

@@ -17,7 +17,39 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Contracts::RateCardCreateParams} for more details.
           #
-          # 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.
           #
           # @overload create(name:, aliases: nil, credit_type_conversions: nil, custom_fields: nil, description: nil, fiat_credit_type_id: nil, request_options: {})
           #
@@ -27,7 +59,7 @@ module MetronomeSDK
           #
           # @param credit_type_conversions [Array<MetronomeSDK::Models::V1::Contracts::RateCardCreateParams::CreditTypeConversion>] Required when using custom pricing units in rates.
           #
-          # @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]
           #
@@ -49,8 +81,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.
           #
           # @overload retrieve(id:, request_options: {})
           #
@@ -74,7 +107,58 @@ module MetronomeSDK
           # Some parameter documentations has been truncated, see
           # {MetronomeSDK::Models::V1::Contracts::RateCardUpdateParams} for more details.
           #
-          # 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
           #
           # @overload update(rate_card_id:, aliases: nil, description: nil, name: nil, request_options: {})
           #
@@ -102,8 +186,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.
           #
           # @overload list(limit: nil, next_page: nil, body: nil, request_options: {})
           #
@@ -131,7 +216,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.
           #
           # @overload archive(id:, request_options: {})
           #
@@ -156,8 +245,18 @@ module MetronomeSDK
           # {MetronomeSDK::Models::V1::Contracts::RateCardRetrieveRateScheduleParams} for
           # more details.
           #
-          # 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.
           #
           # @overload retrieve_rate_schedule(rate_card_id:, starting_at:, limit: nil, next_page: nil, ending_before: nil, selectors: nil, request_options: {})
           #