Class: MetronomeSDK::Resources::V1::Customers::Commits

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v1/customers/commits.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Commits

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

Parameters:



260
261
262
 
# File 'lib/metronome_sdk/resources/v1/customers/commits.rb', line 260

def initialize(client:)
  @client = client
end

Instance Method Details

#create(access_schedule: , customer_id: , priority: , product_id: , type: , applicable_contract_ids: nil, applicable_product_ids: nil, applicable_product_tags: nil, custom_fields: nil, description: nil, invoice_contract_id: nil, invoice_schedule: nil, name: nil, netsuite_sales_order_id: nil, rate_type: nil, salesforce_opportunity_id: nil, specifiers: nil, uniqueness_key: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::Customers::CommitCreateResponse

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

Creates customer-level commits that establish spending commitments for customers across their Metronome usage. Commits represent contracted spending obligations that can be either prepaid (paid upfront) or postpaid (billed later).

Note: In most cases, you should add commitments directly to customer contracts using the contract/create or contract/edit APIs.

### Use this endpoint to:

Use this endpoint when you need to establish customer-level spending commitments that can be applied across multiple contracts or scoped to specific contracts. Customer-level commits are ideal for:

  • Enterprise-wide minimum spending agreements that span multiple contracts

  • Multi-contract volume commitments with shared spending pools

  • Cross-contract discount tiers based on aggregate usage

#### Commit type Requirements:

  • You must specify either “prepaid” or “postpaid” as the commit type:

  • Prepaid commits: Customer pays upfront; invoice_schedule is optional (if omitted, creates a commit without an invoice)

  • Postpaid commits: Customer pays when the commitment expires (the end of the access_schedule); invoice_schedule is required and must match access_schedule totals.

#### Billing configuration:

  • invoice_contract_id is required for postpaid commits and for prepaid commits with billing (only optional for free prepaid commits) unless do_not_invoice is set to true

  • For postpaid commits: access_schedule and invoice_schedule must have matching amounts

  • For postpaid commits: only one schedule item is allowed in both schedules.

#### Scoping flexibility:

Customer-level commits can be configured in a few ways:

  • Contract-specific: Use the ‘applicable_contract_ids` field to limit the commit to specific contracts

  • Cross-contract: Leave ‘applicable_contract_ids` empty to allow the commit to be used across all of the customer’s contracts

#### Product targeting:

Commits can be scoped to specific products using applicable_product_ids, applicable_product_tags, or specifiers, or left unrestricted to apply to all products.

#### Priority considerations:

When multiple commits are applicable, the one with the lower priority value will be consumed first. If there is a tie, contract level commits and credits will be applied before customer level commits and credits. Plan your priority scheme carefully to ensure commits are applied in the desired order.

### Usage guidelines:

⚠️ Preferred Alternative: In most cases, you should add commits directly to contracts using the create contract or edit contract APIs instead of creating customer-level commits. Contract-level commits provide better organization and are the recommended approach for standard use cases.

Parameters:

  • access_schedule (MetronomeSDK::Models::V1::Customers::CommitCreateParams::AccessSchedule) —

    Schedule for distributing the commit to the customer. For “POSTPAID” commits onl

  • customer_id (String)
  • priority (Float) —

    If multiple credits or commits are applicable, the one with the lower priority w

  • product_id (String) —

    ID of the fixed product associated with the commit. This is required because pro

  • type (Symbol, MetronomeSDK::Models::V1::Customers::CommitCreateParams::Type)
  • applicable_contract_ids (Array<String>) —

    Which contract the commit applies to. If not provided, the commit applies to all

  • applicable_product_ids (Array<String>) —

    Which products the commit applies to. If applicable_product_ids, applicable_prod

  • applicable_product_tags (Array<String>) —

    Which tags the commit applies to. If applicable*product_ids, applicable_product*

  • custom_fields (Hash{Symbol=>String}) —

    Custom fields to be added eg. { “key1”: “value1”, “key2”: “value2” }

  • description (String) —

    Used only in UI/API. It is not exposed to end customers.

  • invoice_contract_id (String) —

    The contract that this commit will be billed on. This is required for “POSTPAID”

  • invoice_schedule (MetronomeSDK::Models::V1::Customers::CommitCreateParams::InvoiceSchedule) —

    Required for “POSTPAID” commits: the true up invoice will be generated at this t

  • name (String) —

    displayed on invoices

  • netsuite_sales_order_id (String) —

    This field’s availability is dependent on your client’s configuration.

  • rate_type (Symbol, MetronomeSDK::Models::V1::Customers::CommitCreateParams::RateType)
  • salesforce_opportunity_id (String) —

    This field’s availability is dependent on your client’s configuration.

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

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

  • uniqueness_key (String) —

    Prevents the creation of duplicates. If a request to create a commit or credit i

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

Returns:

See Also:



118
119
120
121
122
123
124
125
126
127
 
# File 'lib/metronome_sdk/resources/v1/customers/commits.rb', line 118

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

#list(customer_id: , commit_id: nil, covering_date: nil, effective_before: nil, include_archived: nil, include_balance: nil, include_contract_commits: nil, include_ledgers: nil, limit: nil, next_page: nil, starting_at: nil, request_options: {}) ⇒ MetronomeSDK::Internal::BodyCursorPage<MetronomeSDK::Models::Commit>

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

Retrieve all commit agreements for a customer, including both prepaid and postpaid commitments. This endpoint provides comprehensive visibility into contractual spending obligations, enabling you to track commitment utilization and manage customer contracts effectively.

### Use this endpoint to:

  • Display commitment balances and utilization in customer dashboards

  • Track prepaid commitment drawdown and remaining balances

  • Monitor postpaid commitment progress toward minimum thresholds

  • Build commitment tracking and forecasting tools

  • Show commitment history with optional ledger details

  • Manage rollover balances between contract periods

### Key response fields:

An array of Commit objects containing:

  • Commit type: PREPAID (pay upfront) or POSTPAID (pay at true-up)

  • Rate type: COMMIT_RATE (discounted) or LIST_RATE (standard pricing)

  • Access schedule: When commitment funds become available

  • Invoice schedule: When the customer is billed

  • Product targeting: Which product(s) usage is eligible to draw from this commit

  • Optional ledger entries: Transaction history (if ‘include_ledgers=true`)

  • Balance information: Current available amount (if ‘include_balance=true`)

  • Rollover settings: Fraction of unused amount that carries forward

### Usage guidelines:

  • Pagination: Results limited to 25 commits per page; use ‘next_page’ for more

  • Date filtering options:

    • ‘covering_date`: Commits active on a specific date

    • ‘starting_at`: Commits with access on/after a date

    • ‘effective_before`: Commits with access before a date (exclusive)

  • Scope options:

    • ‘include_contract_commits`: Include contract-level commits (not just customer-level)

    • ‘include_archived`: Include archived commits and commits from archived contracts

  • Performance considerations:

    • include_ledgers: Adds detailed transaction history (slower)

    • include_balance: Adds current balance calculation (slower)

  • Optional filtering: Use commit_id to retrieve a specific commit

Parameters:

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

    Include only commits that have access schedules that “cover” the provided date

  • effective_before (Time) —

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

  • include_archived (Boolean) —

    Include archived commits and commits from archived contracts.

  • include_balance (Boolean) —

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

  • include_contract_commits (Boolean) —

    Include commits on the contract level.

  • include_ledgers (Boolean) —

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

  • 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 commits that have any access on or after the provided date

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

Returns:

See Also:



205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/metronome_sdk/resources/v1/customers/commits.rb', line 205

def list(params)
  parsed, options = MetronomeSDK::V1::Customers::CommitListParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/contracts/customerCommits/list",
    body: parsed,
    page: MetronomeSDK::Internal::BodyCursorPage,
    model: MetronomeSDK::Commit,
    options: options
  )
end

#update_end_date(commit_id: , customer_id: , access_ending_before: nil, invoices_ending_before: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::Customers::CommitUpdateEndDateResponse

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

Shortens the end date of a prepaid commit to terminate it earlier than originally scheduled. Use this endpoint when you need to cancel or reduce the duration of an existing prepaid commit. Only works with prepaid commit types and can only move the end date forward (earlier), not extend it.

### Usage guidelines:

To extend commit end dates or make other comprehensive edits, use the ‘edit commit’ endpoint instead.

Parameters:

  • commit_id (String) —

    ID of the commit to update. Only supports “PREPAID” commits.

  • customer_id (String) —

    ID of the customer whose commit is to be updated

  • access_ending_before (Time) —

    RFC 3339 timestamp indicating when access to the commit will end and it will no

  • invoices_ending_before (Time) —

    RFC 3339 timestamp indicating when the commit will stop being invoiced (exclusiv

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

Returns:

See Also:



246
247
248
249
250
251
252
253
254
255
 
# File 'lib/metronome_sdk/resources/v1/customers/commits.rb', line 246

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