Class: MetronomeSDK::Resources::V2::Contracts

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v2/contracts.rb,
sig/metronome_sdk/resources/v2/contracts.rbs

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:



386
387
388
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 386

def initialize(client:)
  @client = client
end

Instance Method Details

#edit(contract_id:, customer_id:, add_billing_provider_configuration_update: nil, add_commits: nil, add_credits: nil, add_discounts: nil, add_overrides: nil, add_prepaid_balance_threshold_configuration: nil, add_professional_services: nil, add_recurring_commits: nil, add_recurring_credits: nil, add_reseller_royalties: nil, add_revenue_system_configuration_update: nil, add_scheduled_charges: nil, add_spend_threshold_configuration: nil, add_spend_trackers: nil, add_subscriptions: nil, allow_contract_ending_before_finalized_invoice: nil, archive_commits: nil, archive_credits: nil, archive_scheduled_charges: nil, archive_spend_trackers: nil, remove_overrides: nil, uniqueness_key: nil, update_commits: nil, update_contract_end_date: nil, update_contract_name: nil, update_credits: nil, update_net_payment_terms_days: nil, update_prepaid_balance_threshold_configuration: nil, update_recurring_commits: nil, update_recurring_credits: nil, update_scheduled_charges: nil, update_spend_threshold_configuration: nil, update_subscriptions: nil, request_options: {}) ⇒ MetronomeSDK::Models::V2::ContractEditResponse

Some parameter documentations has been truncated, see Models::V2::ContractEditParams for more details.

The ability to edit a contract helps you react quickly to the needs of your customers and your business.

Use this endpoint to:

  • Encode mid-term commitment and discount changes
  • Fix configuration mistakes and easily roll back packaging changes

Key response fields:

  • The id of the edit
  • Complete edit details. For example, if you edited the contract to add new overrides and credits, you will receive the IDs of those overrides and credits in the response.

Usage guidelines:

  • When you edit a contract, any draft invoices update immediately to reflect that edit. Finalized invoices remain unchanged - you must void and regenerate them in the UI or API to reflect the edit.
  • Contract editing must be enabled to use this endpoint. Reach out to your Metronome representative to learn more.

Parameters:

Returns:

See Also:



208
209
210
211
212
213
214
215
216
217
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 208

def edit(params)
  parsed, options = MetronomeSDK::V2::ContractEditParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v2/contracts/edit",
    body: parsed,
    model: MetronomeSDK::Models::V2::ContractEditResponse,
    options: options
  )
end

#edit_commit(commit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, description: nil, hierarchy_configuration: nil, invoice_contract_id: nil, invoice_schedule: nil, name: nil, priority: nil, product_id: nil, rate_type: nil, specifiers: nil, request_options: {}) ⇒ MetronomeSDK::Models::V2::ContractEditCommitResponse

Some parameter documentations has been truncated, see Models::V2::ContractEditCommitParams for more details.

Edit specific details for a contract-level or customer-level commit. Use this endpoint to modify individual commit access schedules, invoice schedules, applicable products, invoicing contracts, or other fields.

Usage guidelines:

  • As with all edits in Metronome, draft invoices will reflect the edit immediately, while finalized invoices are untouched unless voided and regenerated.
  • If a commit's invoice schedule item is associated with a finalized invoice, you cannot remove or update the invoice schedule item.
  • If a commit's invoice schedule item is associated with a voided invoice, you cannot remove the invoice schedule item.
  • You cannot remove an commit access schedule segment that was applied to a finalized invoice. You can void the invoice beforehand and then remove the access schedule segment.

Parameters:

Returns:

See Also:



274
275
276
277
278
279
280
281
282
283
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 274

def edit_commit(params)
  parsed, options = MetronomeSDK::V2::ContractEditCommitParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v2/contracts/commits/edit",
    body: parsed,
    model: MetronomeSDK::Models::V2::ContractEditCommitResponse,
    options: options
  )
end

#edit_credit(credit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, description: nil, hierarchy_configuration: nil, name: nil, priority: nil, product_id: nil, rate_type: nil, specifiers: nil, request_options: {}) ⇒ MetronomeSDK::Models::V2::ContractEditCreditResponse

Some parameter documentations has been truncated, see Models::V2::ContractEditCreditParams for more details.

Edit details for a contract-level or customer-level credit.

Use this endpoint to:

  • Extend the duration or the amount of an existing free credit like a trial
  • Modify individual credit access schedules, applicable products, priority, or other fields.

Usage guidelines:

  • As with all edits in Metronome, draft invoices will reflect the edit immediately, while finalized invoices are untouched unless voided and regenerated.
  • You cannot remove an access schedule segment that was applied to a finalized invoice. You can void the invoice beforehand and then remove the access schedule segment.

Parameters:

  • credit_id (String) —

    ID of the credit to edit

  • customer_id (String) —

    ID of the customer whose credit is being edited

  • access_schedule (MetronomeSDK::Models::V2::ContractEditCreditParams::AccessSchedule)
  • applicable_product_ids (Array<String>, nil) —

    Which products the credit applies to. If both applicable_product_ids and applica

  • applicable_product_tags (Array<String>, nil) —

    Which tags the credit applies to. If both applicableproduct_ids and applicable

  • description (String) —

    Updated description for the credit

  • hierarchy_configuration (MetronomeSDK::Models::CommitHierarchyConfiguration) —

    Optional configuration for credit hierarchy access control

  • name (String) —

    Updated name for the credit

  • priority (Float, nil) —

    If multiple commits are applicable, the one with the lower priority will apply f

  • product_id (String)
  • rate_type (Symbol, MetronomeSDK::Models::V2::ContractEditCreditParams::RateType) —

    If provided, updates the credit to use the specified rate type for current and f

  • specifiers (Array<MetronomeSDK::Models::CommitSpecifierInput>, nil) —

    List of filters that determine what kind of customer usage draws down a commit o

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

Returns:

See Also:



336
337
338
339
340
341
342
343
344
345
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 336

def edit_credit(params)
  parsed, options = MetronomeSDK::V2::ContractEditCreditParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v2/contracts/credits/edit",
    body: parsed,
    model: MetronomeSDK::Models::V2::ContractEditCreditResponse,
    options: options
  )
end

#get_edit_history(contract_id:, customer_id:, request_options: {}) ⇒ MetronomeSDK::Models::V2::ContractGetEditHistoryResponse

List all the edits made to a contract over time. In Metronome, you can edit a contract at any point after it's created to fix mistakes or reflect changes in terms. Metronome stores a full history of all edits that were ever made to a contract, whether through the UI, editContract endpoint, or other endpoints like updateContractEndDate.

Use this endpoint to:

  • Understand what changes were made to a contract, when, and by who

Key response fields:

  • An array of every edit ever made to the contract
  • Details on each individual edit - for example showing that in one edit, a user added two discounts and incremented a subscription quantity.

Parameters:

Returns:

See Also:



372
373
374
375
376
377
378
379
380
381
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 372

def get_edit_history(params)
  parsed, options = MetronomeSDK::V2::ContractGetEditHistoryParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v2/contracts/getEditHistory",
    body: parsed,
    model: MetronomeSDK::Models::V2::ContractGetEditHistoryResponse,
    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::V2::ContractListResponse

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

For a given customer, lists all of their contracts in chronological order.

Use this endpoint to:

  • Check if a customer is provisioned with any contract, and at which tier
  • Check the duration and terms of a customer's current contract
  • Power a page in your end customer experience that shows the customer's history of tiers (e.g. this customer started out on the Pro Plan, then downgraded to the Starter plan).

Usage guidelines:

Use the starting_at, covering_date, and include_archived parameters to filter the list of returned contracts. For example, to list only currently active contracts, pass covering_date equal to the current time.

Parameters:

  • customer_id (String)
  • covering_date (Time) —

    Optional RFC 3339 timestamp. Only include contracts active on the provided date.

  • 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/credit ledgers in the response. Setting this flag may cause the r

  • starting_at (Time) —

    Optional RFC 3339 timestamp. Only include contracts that started on or after thi

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

Returns:

See Also:



94
95
96
97
98
99
100
101
102
103
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 94

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

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

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

Gets the details for a specific contract, including contract term, rate card information, credits and commits, and more.

Use this endpoint to:

  • Check the duration of a customer's current contract
  • Get details on contract terms, including access schedule amounts for commitments and credits
  • Understand the state of a contract at a past time. As you can evolve the terms of a contract over time through editing, use the as_of_date parameter to view the full contract configuration as of that point in time.

Usage guidelines:

  • Optionally, use the include_balance and include_ledger fields to include balances and ledgers in the credit and commit responses. Using these fields will cause the query to be slower.

Parameters:

  • contract_id (String)
  • customer_id (String)
  • as_of_date (Time) —

    Optional RFC 3339 timestamp. Return the contract as of this date. Cannot be used

  • include_balance (Boolean) —

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

  • include_ledgers (Boolean) —

    Include commit/credit ledgers in the response. Setting this flag may cause the q

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

Returns:

See Also:



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/metronome_sdk/resources/v2/contracts.rb', line 45

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