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

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:



844
845
846
847
848
849
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 844

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:



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

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](/guides/implement-metronome/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.

Parameters:

Returns:

See Also:



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

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:



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

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, 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 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](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](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](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](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](docs.metronome.com/manage-product-access/spend-thresholds/) and [Prepaid Balance Thresholds](docs.metronome.com/manage-product-access/prepaid-balance-thresholds/).

### Usage guidelines:

Parameters:

Returns:

See Also:



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

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:



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

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](docs.metronome.com/api-reference/credits-and-commits/list-balances) 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:



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

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

#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:



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

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](docs.metronome.com/api-reference/credits-and-commits/get-the-net-balance-of-a-customer) 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:



641
642
643
644
645
646
647
648
649
650
651
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 641

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

#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:



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

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:



683
684
685
686
687
688
689
690
691
692
693
694
695
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 683

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:



718
719
720
721
722
723
724
725
726
727
728
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 718

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:



752
753
754
755
756
757
758
759
760
761
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 752

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:



794
795
796
797
798
799
800
801
802
803
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 794

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:



830
831
832
833
834
835
836
837
838
839
 
# File 'lib/metronome_sdk/resources/v1/contracts.rb', line 830

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