metronome-sdk 0.3.0 → 1.0.0

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

@@ -16,7 +16,129 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractCreateParams} for more details.
         #
-        # 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).
         #
         # @overload create(customer_id:, starting_at:, billing_provider_configuration: nil, commits: nil, credits: nil, custom_fields: nil, discounts: nil, ending_before: nil, hierarchy_configuration: nil, multiplier_override_prioritization: nil, name: nil, net_payment_terms_days: nil, netsuite_sales_order_id: nil, overrides: nil, prepaid_balance_threshold_configuration: nil, priority: nil, professional_services: nil, rate_card_alias: nil, rate_card_id: nil, recurring_commits: nil, recurring_credits: nil, reseller_royalties: nil, salesforce_opportunity_id: nil, scheduled_charges: nil, scheduled_charges_on_usage_invoices: nil, spend_threshold_configuration: nil, subscriptions: nil, total_contract_value: nil, transition: nil, uniqueness_key: nil, usage_filter: nil, usage_statement_schedule: nil, request_options: {})
         #
@@ -30,7 +152,7 @@ module MetronomeSDK
         #
         # @param credits [Array<MetronomeSDK::Models::V1::ContractCreateParams::Credit>]
         #
-        # @param custom_fields [Hash{Symbol=>String}]
+        # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
         #
         # @param discounts [Array<MetronomeSDK::Models::V1::ContractCreateParams::Discount>] This field's availability is dependent on your client's configuration.
         #
@@ -48,7 +170,7 @@ module MetronomeSDK
         #
         # @param overrides [Array<MetronomeSDK::Models::V1::ContractCreateParams::Override>]
         #
-        # @param prepaid_balance_threshold_configuration [MetronomeSDK::Models::V1::ContractCreateParams::PrepaidBalanceThresholdConfiguration]
+        # @param prepaid_balance_threshold_configuration [MetronomeSDK::Models::PrepaidBalanceThresholdConfiguration]
         #
         # @param priority [Float] Priority of the contract.
         #
@@ -70,7 +192,7 @@ module MetronomeSDK
         #
         # @param scheduled_charges_on_usage_invoices [Symbol, MetronomeSDK::Models::V1::ContractCreateParams::ScheduledChargesOnUsageInvoices] Determines which scheduled and commit charges to consolidate onto the Contract's
         #
-        # @param spend_threshold_configuration [MetronomeSDK::Models::V1::ContractCreateParams::SpendThresholdConfiguration]
+        # @param spend_threshold_configuration [MetronomeSDK::Models::SpendThresholdConfiguration]
         #
         # @param subscriptions [Array<MetronomeSDK::Models::V1::ContractCreateParams::Subscription>] Optional list of [subscriptions](https://docs.metronome.com/manage-product-acces
         #
@@ -135,8 +257,13 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractListParams} for more details.
         #
-        # 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.
         #
         # @overload list(customer_id:, covering_date: nil, include_archived: nil, include_balance: nil, include_ledgers: nil, starting_at: nil, request_options: {})
         #
@@ -172,7 +299,24 @@ module MetronomeSDK
         # {MetronomeSDK::Models::V1::ContractAddManualBalanceEntryParams} for more
         # details.
         #
-        # 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.
         #
         # @overload add_manual_balance_entry(id:, amount:, customer_id:, reason:, segment_id:, contract_id: nil, timestamp: nil, request_options: {})
         #
@@ -207,7 +351,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.
@@ -224,7 +368,7 @@ module MetronomeSDK
         #
         # @param credits [Array<MetronomeSDK::Models::V1::ContractAmendParams::Credit>]
         #
-        # @param custom_fields [Hash{Symbol=>String}]
+        # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
         #
         # @param discounts [Array<MetronomeSDK::Models::V1::ContractAmendParams::Discount>] This field's availability is dependent on your client's configuration.
         #
@@ -261,7 +405,26 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractArchiveParams} for more details.
         #
-        # 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.
         #
         # @overload archive(contract_id:, customer_id:, void_invoices:, request_options: {})
         #
@@ -287,7 +450,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.
         #
         # @overload create_historical_invoices(invoices:, preview:, request_options: {})
         #
@@ -312,7 +479,40 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractListBalancesParams} for more details.
         #
-        # 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
         #
         # @overload list_balances(customer_id:, id: nil, covering_date: nil, effective_before: nil, include_archived: nil, include_balance: nil, include_contract_balances: nil, include_ledgers: nil, limit: nil, next_page: nil, starting_at: nil, request_options: {})
         #
@@ -340,7 +540,7 @@ module MetronomeSDK
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [MetronomeSDK::Models::V1::ContractListBalancesResponse]
+        # @return [MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::Commit, MetronomeSDK::Models::Credit>]
         #
         # @see MetronomeSDK::Models::V1::ContractListBalancesParams
         def list_balances(params)
@@ -349,6 +549,7 @@ module MetronomeSDK
             method: :post,
             path: "v1/contracts/customerBalances/list",
             body: parsed,
+            page: MetronomeSDK::Internal::BodyCursorPage,
             model: MetronomeSDK::Models::V1::ContractListBalancesResponse,
             options: options
           )
@@ -357,7 +558,13 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractRetrieveRateScheduleParams} for more details.
         #
-        # 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.
         #
         # @overload retrieve_rate_schedule(contract_id:, customer_id:, limit: nil, next_page: nil, at: nil, selectors: nil, request_options: {})
         #
@@ -391,8 +598,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.
         #
         # @overload retrieve_subscription_quantity_history(contract_id:, customer_id:, subscription_id:, request_options: {})
         #
@@ -449,7 +664,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.
         #
         # @overload set_usage_filter(contract_id:, customer_id:, group_key:, group_values:, starting_at:, request_options: {})
         #
@@ -477,7 +709,11 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractUpdateEndDateParams} for more details.
         #
-        # Update the end date of a contract
+        # Update or and 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. Use this if a contract's end date
+        # has changed or if a perpetual contract ends.
         #
         # @overload update_end_date(contract_id:, customer_id:, allow_ending_before_finalized_invoice: nil, ending_before: nil, request_options: {})
         #

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

@@ -147,7 +147,7 @@ module MetronomeSDK
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [MetronomeSDK::Models::V1::CreditGrantListEntriesResponse]
+        # @return [MetronomeSDK::Internal::CursorPageWithoutLimit<MetronomeSDK::Models::V1::CreditGrantListEntriesResponse>]
         #
         # @see MetronomeSDK::Models::V1::CreditGrantListEntriesParams
         def list_entries(params = {})
@@ -158,6 +158,7 @@ module MetronomeSDK
             path: "v1/credits/listEntries",
             query: parsed.slice(*query_params),
             body: parsed.except(*query_params),
+            page: MetronomeSDK::Internal::CursorPageWithoutLimit,
             model: MetronomeSDK::Models::V1::CreditGrantListEntriesResponse,
             options: options
           )

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

@@ -4,8 +4,35 @@ module MetronomeSDK
   module Resources
     class V1
       class CustomFields
-        # Add a key to the allow list for a given entity. There is a 100 character limit
-        # on custom field keys.
+        # Creates a new custom field key for a given entity (e.g. billable metric,
+        # contract, alert).
+        #
+        # Custom fields are properties that you can add to Metronome objects to store
+        # metadata like foreign keys or other descriptors. This metadata can get
+        # transferred to or accessed by other systems to contextualize Metronome data and
+        # power business processes. For example, to service workflows like revenue
+        # recognition, reconciliation, and invoicing, custom fields help Metronome know
+        # the relationship between entities in the platform and third-party systems.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Create a new custom field key for Customer objects in Metronome. You can then
+        #   use the Set Custom Field Values endpoint to set the value of this key for a
+        #   specific customer.
+        # - Specify whether the key should enforce uniqueness. If the key is set to
+        #   enforce uniqueness and you attempt to set a custom field value for the key
+        #   that already exists, it will fail.
+        #
+        # ### Usage guidelines:
+        #
+        # - Custom fields set on commits, credits, and contracts can be used to scope
+        #   alert evaluation. For example, you can create a spend threshold alert that
+        #   only considers spend associated with contracts with custom field key
+        #   `contract_type` and value `paygo`
+        # - Custom fields set on products can be used in the Stripe integration to set
+        #   metadata on invoices.
+        # - Custom fields for customers, contracts, invoices, products, commits, scheduled
+        #   charges, and subscriptions are passed down to the invoice.
         #
         # @overload add_key(enforce_uniqueness:, entity:, key:, request_options: {})
         #
@@ -28,7 +55,10 @@ module MetronomeSDK
           )
         end
 
-        # Deletes one or more custom fields on an instance of a Metronome entity.
+        # Remove specific custom field values from a Metronome entity instance by
+        # specifying the field keys to delete. Use this endpoint to clean up unwanted
+        # custom field data while preserving other fields on the same entity. Requires the
+        # entity type, entity ID, and array of keys to remove.
         #
         # @overload delete_values(entity:, entity_id:, keys:, request_options: {})
         #
@@ -51,7 +81,10 @@ module MetronomeSDK
           )
         end
 
-        # List all active custom field keys, optionally filtered by entity type.
+        # Retrieve all your active custom field keys, with optional filtering by entity
+        # type (customer, contract, product, etc.). Use this endpoint to discover what
+        # custom field keys are available before setting values on entities or to audit
+        # your custom field configuration across different entity types.
         #
         # @overload list_keys(next_page: nil, entities: nil, request_options: {})
         #
@@ -61,7 +94,7 @@ module MetronomeSDK
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [MetronomeSDK::Models::V1::CustomFieldListKeysResponse]
+        # @return [MetronomeSDK::Internal::CursorPageWithoutLimit<MetronomeSDK::Models::V1::CustomFieldListKeysResponse>]
         #
         # @see MetronomeSDK::Models::V1::CustomFieldListKeysParams
         def list_keys(params = {})
@@ -72,12 +105,16 @@ module MetronomeSDK
             path: "v1/customFields/listKeys",
             query: parsed.slice(*query_params),
             body: parsed.except(*query_params),
+            page: MetronomeSDK::Internal::CursorPageWithoutLimit,
             model: MetronomeSDK::Models::V1::CustomFieldListKeysResponse,
             options: options
           )
         end
 
-        # Remove a key from the allow list for a given entity.
+        # Removes a custom field key from the allowlist for a specific entity type,
+        # preventing future use of that key across all instances of the entity. Existing
+        # values for this key on entity instances will no longer be accessible once the
+        # key is removed.
         #
         # @overload remove_key(entity:, key:, request_options: {})
         #
@@ -99,19 +136,19 @@ module MetronomeSDK
           )
         end
 
-        # Sets one or more custom fields on an instance of a Metronome entity. If a
-        # key/value pair passed in this request matches one already set on the entity, its
-        # value will be overwritten. Any key/value pairs that exist on the entity that do
-        # not match those passed in this request will remain untouched. This endpoint is
-        # transactional and will update all key/value pairs or no key/value pairs. Partial
-        # updates are not supported. There is a 200 character limit on custom field
-        # values.
+        # Sets custom field values on a specific Metronome entity instance. Overwrites
+        # existing values for matching keys while preserving other fields. All updates are
+        # transactional—either all values are set or none are. Custom field values are
+        # limited to 200 characters each.
         #
         # @overload set_values(custom_fields:, entity:, entity_id:, request_options: {})
         #
-        # @param custom_fields [Hash{Symbol=>String}]
+        # @param custom_fields [Hash{Symbol=>String}] Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
+        #
         # @param entity [Symbol, MetronomeSDK::Models::V1::CustomFieldSetValuesParams::Entity]
+        #
         # @param entity_id [String]
+        #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [nil]