Class: MetronomeSDK::Resources::V1::Contracts

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v1/contracts.rb,
lib/metronome_sdk/resources/v1/contracts/products.rb,
lib/metronome_sdk/resources/v1/contracts/rate_cards.rb,
lib/metronome_sdk/resources/v1/contracts/named_schedules.rb,
lib/metronome_sdk/resources/v1/contracts/rate_cards/rates.rb,
lib/metronome_sdk/resources/v1/contracts/rate_cards/product_orders.rb,
lib/metronome_sdk/resources/v1/contracts/rate_cards/named_schedules.rb,
sig/metronome_sdk/resources/v1/contracts.rbs,
sig/metronome_sdk/resources/v1/contracts/products.rbs,
sig/metronome_sdk/resources/v1/contracts/rate_cards.rbs,
sig/metronome_sdk/resources/v1/contracts/named_schedules.rbs,
sig/metronome_sdk/resources/v1/contracts/rate_cards/rates.rbs,
sig/metronome_sdk/resources/v1/contracts/rate_cards/product_orders.rbs,
sig/metronome_sdk/resources/v1/contracts/rate_cards/named_schedules.rbs

Defined Under Namespace

Classes: NamedSchedules, Products, RateCards

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Contracts

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Contracts.

Parameters:



980
981
982
983
984
985
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 980

def initialize(client:)
  @client = client
  @products = MetronomeSDK::Resources::V1::Contracts::Products.new(client: client)
  @rate_cards = MetronomeSDK::Resources::V1::Contracts::RateCards.new(client: client)
  @named_schedules = MetronomeSDK::Resources::V1::Contracts::NamedSchedules.new(client: client)
end

Instance Attribute Details

#named_schedules ⇒ MetronomeSDK::Resources::V1::Contracts::NamedSchedules (readonly)

Named schedules are used for storing custom data that can change over time. Named schedules are often used in custom pricing logic.

Returns:



18
19
20
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 18

def named_schedules
  @named_schedules
end

#products ⇒ MetronomeSDK::Resources::V1::Contracts::Products (readonly)

Products are the items that customers purchase.

Returns:



9
10
11
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 9

def products
  @products
end

#rate_cards ⇒ MetronomeSDK::Resources::V1::Contracts::RateCards (readonly)

Rate cards are used to define default pricing for products.

Returns:



13
14
15
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 13

def rate_cards
  @rate_cards
end

Instance Method Details

#add_manual_balance_entry(id:, amount:, customer_id:, reason:, segment_id:, contract_id: nil, per_group_amounts: nil, timestamp: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::V1::ContractAddManualBalanceEntryParams for more details.

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.

Parameters:

  • id (String) —

    ID of the balance (commit or credit) to update.

  • amount (Float) —

    Amount to add to the segment. A negative number will draw down from the balance.

  • customer_id (String) —

    ID of the customer whose balance is to be updated.

  • reason (String) —

    Reason for the manual adjustment. This will be displayed in the ledger.

  • segment_id (String) —

    ID of the segment to update.

  • contract_id (String) —

    ID of the contract to update. Leave blank to update a customer level balance.

  • per_group_amounts (Hash{Symbol=>Float}) —

    If using individually configured commits/credits attached to seat managed subscr

  • timestamp (Time) —

    RFC 3339 timestamp indicating when the manual adjustment takes place. If not pro

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 354

def add_manual_balance_entry(params)
  parsed, options = MetronomeSDK::V1::ContractAddManualBalanceEntryParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/addManualBalanceLedgerEntry",
    body: parsed,
    model: NilClass,
    options: options
  )
end

#amend(contract_id:, customer_id:, starting_at:, commits: nil, credits: nil, custom_fields: nil, discounts: nil, netsuite_sales_order_id: nil, overrides: nil, professional_services: nil, reseller_royalties: nil, salesforce_opportunity_id: nil, scheduled_charges: nil, total_contract_value: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractAmendResponse

Amendments will be replaced by Contract editing. New clients should implement using the editContract endpoint. Read more about the migration to contract editing here and reach out to your Metronome representative for more details. Once contract editing is enabled, access to this endpoint will be removed.

Parameters:

Returns:

See Also:



406
407
408
409
410
411
412
413
414
415
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 406

def amend(params)
  parsed, options = MetronomeSDK::V1::ContractAmendParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/amend",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractAmendResponse,
    options: options
  )
end

#archive(contract_id:, customer_id:, void_invoices:, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractArchiveResponse

Some parameter documentations has been truncated, see Models::V1::ContractArchiveParams for more details.

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.

Parameters:

  • contract_id (String) —

    ID of the contract to archive

  • customer_id (String) —

    ID of the customer whose contract is to be archived

  • void_invoices (Boolean) —

    If false, the existing finalized invoices will remain after the contract is arch

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



454
455
456
457
458
459
460
461
462
463
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 454

def archive(params)
  parsed, options = MetronomeSDK::V1::ContractArchiveParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/archive",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractArchiveResponse,
    options: options
  )
end

#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, package_alias: nil, package_id: nil, prepaid_balance_threshold_configuration: nil, professional_services: nil, rate_card_alias: nil, rate_card_id: nil, recurring_commits: nil, recurring_credits: nil, reseller_royalties: nil, revenue_system_configuration: nil, salesforce_opportunity_id: nil, scheduled_charges: nil, scheduled_charges_on_usage_invoices: nil, spend_threshold_configuration: nil, spend_trackers: nil, subscriptions: nil, total_contract_value: nil, transition: nil, uniqueness_key: nil, usage_filter: nil, usage_statement_schedule: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractCreateResponse

Some parameter documentations has been truncated, see Models::V1::ContractCreateParams for more details.

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 grant 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.

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.

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.

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.

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 and Prepaid Balance Thresholds.

Usage guidelines:

  • You can always Edit Contracts 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.

Parameters:

Returns:

See Also:



224
225
226
227
228
229
230
231
232
233
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 224

def create(params)
  parsed, options = MetronomeSDK::V1::ContractCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/create",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractCreateResponse,
    options: options
  )
end

#create_historical_invoices(invoices:, preview:, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractCreateHistoricalInvoicesResponse

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.

Parameters:

Returns:

See Also:



480
481
482
483
484
485
486
487
488
489
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 480

def create_historical_invoices(params)
  parsed, options = MetronomeSDK::V1::ContractCreateHistoricalInvoicesParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/createHistoricalInvoices",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractCreateHistoricalInvoicesResponse,
    options: options
  )
end

#get_net_balance(customer_id:, credit_type_id: nil, filters: nil, invoice_inclusion_mode: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractGetNetBalanceResponse

Some parameter documentations has been truncated, see Models::V1::ContractGetNetBalanceParams for more details.

Retrieve the combined current balance across any grouping of credits and commits for a customer in a single API call.

  • Display real-time available balance to customers in billing dashboards
  • Build finance dashboards showing credit utilization across customer segments
  • Validate expected vs. actual balance during billing reconciliation

Key response fields:

  • balance: The combined net balance available to use at this moment across all matching commits and credits
  • credit_type_id: The credit type (fiat or custom pricing unit) the balance is denominated in

Filtering options:

Balance filters allow you to scope the calculation to specific subsets of commits and credits. When using multiple filter objects, they are OR'd together — if a commit or credit matches any filter, it's included in the net balance. Within a single filter object, all specified conditions are AND'd together.

  • Balance types: Include any combination of PREPAID_COMMIT, POSTPAID_COMMIT, and CREDIT (e.g., ["PREPAID_COMMIT", "CREDIT"] to exclude postpaid commits). If not specified, all balance types are included.
  • Specific IDs: Target exact commit or credit IDs for precise balance queries
  • Custom fields: Filter by custom field key-value pairs; when multiple pairs are provided, commits must match all of them

Example: To get the balance of all free-trial credits OR all signup-promotion commits, you'd pass two filter objects — one filtering for CREDIT with custom field campaign: free-trial, and another filtering for PREPAID_COMMIT with custom field campaign: signup-promotion.

Usage guidelines:

  • Balance ledger details: Use the listBalances endpoint instead to understand detailed ledger drawdowns for each individual balance
  • Draft invoice handling: Use invoice_inclusion_mode to control whether pending draft invoice deductions are included (FINALIZED_AND_DRAFT, the default) or excluded (FINALIZED) from the balance calculation
  • Account hierarchies: When querying a child customer, shared commits from parent contracts are not included — query the parent customer directly to see shared commit balances
  • Negative balances: Manual ledger entries can cause negative segment balances; these are treated as zero when calculating the net balance
  • Credit types: If credit_type_id is not specified, the balance defaults to USD (cents)

Parameters:

Returns:

See Also:



560
561
562
563
564
565
566
567
568
569
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 560

def get_net_balance(params)
  parsed, options = MetronomeSDK::V1::ContractGetNetBalanceParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/customerBalances/getNetBalance",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractGetNetBalanceResponse,
    options: options
  )
end

#get_subscription_seats_history(contract_id:, customer_id:, subscription_id:, covering_date: nil, cursor: nil, ending_before: nil, limit: nil, starting_at: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractGetSubscriptionSeatsHistoryResponse

Some parameter documentations has been truncated, see Models::V1::ContractGetSubscriptionSeatsHistoryParams for more details.

Get the history of subscription seats schedule over time for a given subscription_id. This endpoint provides information about seat assignments and total quantities for different time periods, allowing you to track how seat assignments have changed over time.

Use this endpoint to:

  • Track changes to seat assignments over time
  • Get seat schedule for a specific date using the covering_date parameter
  • Get seat schedule history with optional date range filtering using starting_at and ending_before

Key response fields:

  • data: array of seat schedule entries with time periods, quantity, and assignments
  • next_page: cursor for pagination to retrieve additional results

Usage guidelines:

  • Use covering_date to get the active seats for a specific point in time. covering_date cannot be used with starting_at or ending_before.
  • Use starting_at and ending_before to filter results by time range. starting_at and ending_before cannot be used with covering_date.
  • Maximum limit is 10 seat schedule entries per request
  • Results are ordered by starting_at timestamp

Parameters:

  • contract_id (String)
  • customer_id (String)
  • subscription_id (String)
  • covering_date (Time, nil) —

    Get the seats history segment for the covering date. Cannot be used with `starti

  • cursor (String, nil) —

    Cursor for pagination. Use the value from the next_page field of the previous

  • ending_before (Time, nil) —

    Include seats history segments that are active at or before this timestamp. Use

  • limit (Integer, nil) —

    Maximum number of seat schedule entries to return. Defaults to 10. Required rang

  • starting_at (Time, nil) —

    Include seats history segments that are active at or after this timestamp. Use w

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



625
626
627
628
629
630
631
632
633
634
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 625

def get_subscription_seats_history(params)
  parsed, options = MetronomeSDK::V1::ContractGetSubscriptionSeatsHistoryParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/getSubscriptionSeatsHistory",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractGetSubscriptionSeatsHistoryResponse,
    options: options
  )
end

#list(customer_id:, covering_date: nil, include_archived: nil, include_balance: nil, include_ledgers: nil, starting_at: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractListResponse

Some parameter documentations has been truncated, see Models::V1::ContractListParams for more details.

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.

Parameters:

  • customer_id (String)
  • covering_date (Time) —

    Optional RFC 3339 timestamp. If provided, the response will include only contrac

  • include_archived (Boolean) —

    Include archived contracts in the response

  • include_balance (Boolean) —

    Include the balance of credits and commits in the response. Setting this flag ma

  • include_ledgers (Boolean) —

    Include commit ledgers in the response. Setting this flag may cause the query to

  • starting_at (Time) —

    Optional RFC 3339 timestamp. If provided, the response will include only contrac

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



297
298
299
300
301
302
303
304
305
306
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 297

def list(params)
  parsed, options = MetronomeSDK::V1::ContractListParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/list",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractListResponse,
    options: options
  )
end

#list_balances(customer_id:, id: nil, covering_date: nil, effective_before: nil, exclude_zero_balances: nil, include_archived: nil, include_balance: nil, include_contract_balances: nil, include_ledgers: nil, limit: nil, next_page: nil, starting_at: nil, request_options: {}) ⇒ MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::Commit, MetronomeSDK::Models::Credit>

Some parameter documentations has been truncated, see Models::V1::ContractListBalancesParams for more details.

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:

  • Use the getNetBalance endpoint to retrieve a single combined current balance
  • 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

Parameters:

  • customer_id (String)
  • id (String)
  • covering_date (Time) —

    Return only balances that have access schedules that "cover" the provided date

  • effective_before (Time) —

    Include only balances that have any access before the provided date (exclusive)

  • exclude_zero_balances (Boolean) —

    Exclude balances with zero amounts from the response.

  • include_archived (Boolean) —

    Include archived credits and credits from archived contracts.

  • include_balance (Boolean) —

    Include the balance of credits and commits in the response. Setting this flag ma

  • include_contract_balances (Boolean) —

    Include balances on the contract level.

  • include_ledgers (Boolean) —

    Include ledgers in the response. Setting this flag may cause the query to be slo

  • limit (Integer) —

    The maximum number of commits to return. Defaults to 25.

  • next_page (String) —

    The next page token from a previous response.

  • starting_at (Time) —

    Include only balances that have any access on or after the provided date

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



708
709
710
711
712
713
714
715
716
717
718
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 708

def list_balances(params)
  parsed, options = MetronomeSDK::V1::ContractListBalancesParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/customerBalances/list",
    body: parsed,
    page: MetronomeSDK::Internal::BodyCursorPage,
    model: MetronomeSDK::Models::V1::ContractListBalancesResponse,
    options: options
  )
end

#list_seat_balances(contract_id:, customer_id:, covering_date: nil, cursor: nil, effective_before: nil, include_credits_and_commits: nil, include_ledgers: nil, limit: nil, seat_ids: nil, skip_missing_seat_ids: nil, starting_at: nil, subscription_ids: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractListSeatBalancesResponse

Some parameter documentations has been truncated, see Models::V1::ContractListSeatBalancesParams for more details.

Retrieve detailed balance for seat-based credits and commits from the contract's subscriptions, broken down by individual seats.

Use this endpoint to:

  • Display per-seat balance information in customer dashboards
  • Filter balance data by subscription or specific seats

Key response fields:

An array of seat balance objects containing:

  • Seat id
  • Balance: current total balance across all commits and credits

Usage guidelines:

  • Date filtering: use covering_date OR starting_at/ending_before to filter balance data by time range
  • Set include_credits_and_commits=true for detailed commits and credits breakdown per seat
  • Set include_ledgers=true for detailed transaction history per commit/credit per seat

Parameters:

  • contract_id (String) —

    The contract ID to retrieve seat balances for

  • customer_id (String) —

    The customer ID to retrieve seat balances for

  • covering_date (Time) —

    Include only commits or credits with access that cover this specific date (canno

  • cursor (String) —

    Page token from a previous response to retrieve the next page

  • effective_before (Time) —

    Include only commits or credits with access effective on or before this date (ca

  • include_credits_and_commits (Boolean) —

    Include credits and commits in the response

  • include_ledgers (Boolean) —

    Include ledger entries for each commit and commit. include_credits_and_commits

  • limit (Integer) —

    Maximum number of seats to return. Range: 1-100. Default: 25.

  • seat_ids (Array<String>) —

    Optional filter to only include specific seats.

  • skip_missing_seat_ids (Boolean) —

    When true, any seat_ids not found in contract subscriptions will be silently omi

  • starting_at (Time) —

    Include only commits or credits with access effective on or after this date (can

  • subscription_ids (Array<String>) —

    Optional filter to only include seats from specific subscriptions. If subscripti

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



778
779
780
781
782
783
784
785
786
787
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 778

def list_seat_balances(params)
  parsed, options = MetronomeSDK::V1::ContractListSeatBalancesParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/seatBalances/list",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractListSeatBalancesResponse,
    options: options
  )
end

#retrieve(contract_id:, customer_id:, include_balance: nil, include_ledgers: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractRetrieveResponse

Some parameter documentations has been truncated, see Models::V1::ContractRetrieveParams for more details.

This is the v1 endpoint to get a contract. New clients should implement using the v2 endpoint.

Parameters:

  • contract_id (String)
  • customer_id (String)
  • include_balance (Boolean) —

    Include the balance of credits and commits in the response. Setting this flag ma

  • include_ledgers (Boolean) —

    Include commit ledgers in the response. Setting this flag may cause the query to

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



256
257
258
259
260
261
262
263
264
265
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 256

def retrieve(params)
  parsed, options = MetronomeSDK::V1::ContractRetrieveParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/get",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractRetrieveResponse,
    options: options
  )
end

#retrieve_rate_schedule(contract_id:, customer_id:, limit: nil, next_page: nil, at: nil, selectors: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractRetrieveRateScheduleResponse

Some parameter documentations has been truncated, see Models::V1::ContractRetrieveRateScheduleParams for more details.

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.

Parameters:

  • contract_id (String) —

    Body param: ID of the contract to get the rate schedule for.

  • customer_id (String) —

    Body param: ID of the customer for whose contract to get the rate schedule for.

  • limit (Integer) —

    Query param: Max number of results that should be returned

  • next_page (String) —

    Query param: Cursor that indicates where the next page of results should start.

  • at (Time) —

    Body param: optional timestamp which overlaps with the returned rate schedule se

  • selectors (Array<MetronomeSDK::Models::V1::ContractRetrieveRateScheduleParams::Selector>) —

    Body param: List of rate selectors, rates matching ANY of the selectors will be

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



819
820
821
822
823
824
825
826
827
828
829
830
831
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 819

def retrieve_rate_schedule(params)
  query_params = [:limit, :next_page]
  parsed, options = MetronomeSDK::V1::ContractRetrieveRateScheduleParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :post,
    path: "v1/contracts/getContractRateSchedule",
    query: query,
    body: parsed.except(*query_params),
    model: MetronomeSDK::Models::V1::ContractRetrieveRateScheduleResponse,
    options: options
  )
end

#retrieve_subscription_quantity_history(contract_id:, customer_id:, subscription_id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractRetrieveSubscriptionQuantityHistoryResponse

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.

Parameters:

  • contract_id (String)
  • customer_id (String)
  • subscription_id (String)
  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



854
855
856
857
858
859
860
861
862
863
864
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 854

def retrieve_subscription_quantity_history(params)
  parsed, options =
    MetronomeSDK::V1::ContractRetrieveSubscriptionQuantityHistoryParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/getSubscriptionQuantityHistory",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractRetrieveSubscriptionQuantityHistoryResponse,
    options: options
  )
end

#schedule_pro_services_invoice(contract_id:, customer_id:, issued_at:, line_items:, netsuite_invoice_header_end: nil, netsuite_invoice_header_start: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractScheduleProServicesInvoiceResponse

Create a new scheduled invoice for Professional Services terms on a contract. This endpoint's availability is dependent on your client's configuration.

Parameters:

Returns:

See Also:



888
889
890
891
892
893
894
895
896
897
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 888

def schedule_pro_services_invoice(params)
  parsed, options = MetronomeSDK::V1::ContractScheduleProServicesInvoiceParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/scheduleProServicesInvoice",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractScheduleProServicesInvoiceResponse,
    options: options
  )
end

#set_usage_filter(contract_id:, customer_id:, group_key:, group_values:, starting_at:, request_options: {}) ⇒ nil

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.

Parameters:

  • contract_id (String)
  • customer_id (String)
  • group_key (String)
  • group_values (Array<String>)
  • starting_at (Time)
  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



930
931
932
933
934
935
936
937
938
939
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 930

def set_usage_filter(params)
  parsed, options = MetronomeSDK::V1::ContractSetUsageFilterParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/setUsageFilter",
    body: parsed,
    model: NilClass,
    options: options
  )
end

#update_end_date(contract_id:, customer_id:, allow_ending_before_finalized_invoice: nil, ending_before: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::ContractUpdateEndDateResponse

Some parameter documentations has been truncated, see Models::V1::ContractUpdateEndDateParams for more details.

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.

Parameters:

  • contract_id (String) —

    ID of the contract to update

  • customer_id (String) —

    ID of the customer whose contract is to be updated

  • allow_ending_before_finalized_invoice (Boolean) —

    If true, allows setting the contract end date earlier than the end_timestamp of

  • ending_before (Time) —

    RFC 3339 timestamp indicating when the contract will end (exclusive). If not pro

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



966
967
968
969
970
971
972
973
974
975
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 966

def update_end_date(params)
  parsed, options = MetronomeSDK::V1::ContractUpdateEndDateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/updateEndDate",
    body: parsed,
    model: MetronomeSDK::Models::V1::ContractUpdateEndDateResponse,
    options: options
  )
end