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

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v1/customers.rb,
lib/metronome_sdk/resources/v1/customers/plans.rb,
lib/metronome_sdk/resources/v1/customers/alerts.rb,
lib/metronome_sdk/resources/v1/customers/commits.rb,
lib/metronome_sdk/resources/v1/customers/credits.rb,
lib/metronome_sdk/resources/v1/customers/invoices.rb,
lib/metronome_sdk/resources/v1/customers/billing_config.rb,
lib/metronome_sdk/resources/v1/customers/named_schedules.rb

Defined Under Namespace

Classes: Alerts, BillingConfig, Commits, Credits, Invoices, NamedSchedules, Plans

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Customers

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

Parameters:



596
597
598
599
600
601
602
603
604
605
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 596

def initialize(client:)
  @client = client
  @alerts = MetronomeSDK::Resources::V1::Customers::Alerts.new(client: client)
  @plans = MetronomeSDK::Resources::V1::Customers::Plans.new(client: client)
  @invoices = MetronomeSDK::Resources::V1::Customers::Invoices.new(client: client)
  @billing_config = MetronomeSDK::Resources::V1::Customers::BillingConfig.new(client: client)
  @commits = MetronomeSDK::Resources::V1::Customers::Commits.new(client: client)
  @credits = MetronomeSDK::Resources::V1::Customers::Credits.new(client: client)
  @named_schedules = MetronomeSDK::Resources::V1::Customers::NamedSchedules.new(client: client)
end

Instance Attribute Details

#alerts ⇒ MetronomeSDK::Resources::V1::Customers::Alerts (readonly)

[Alerts](docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)

Returns:



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

def alerts
  @alerts
end

#billing_config ⇒ MetronomeSDK::Resources::V1::Customers::BillingConfig (readonly)

[Customers](docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration.

Returns:



34
35
36
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 34

def billing_config
  @billing_config
end

#commits ⇒ MetronomeSDK::Resources::V1::Customers::Commits (readonly)

Credits and commits are used to manage customer balances.

Returns:



38
39
40
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 38

def commits
  @commits
end

#credits ⇒ MetronomeSDK::Resources::V1::Customers::Credits (readonly)

Credits and commits are used to manage customer balances.

Returns:



42
43
44
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 42

def credits
  @credits
end

#invoices ⇒ MetronomeSDK::Resources::V1::Customers::Invoices (readonly)

[Invoices](docs.metronome.com/invoicing/) reflect how much a customer spent during a period, which is the basis for billing. Metronome automatically generates invoices based upon your pricing, packaging, and usage events. Use these endpoints to retrieve invoices.

Returns:



27
28
29
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 27

def invoices
  @invoices
end

#named_schedules ⇒ MetronomeSDK::Resources::V1::Customers::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:



47
48
49
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 47

def named_schedules
  @named_schedules
end

#plans ⇒ MetronomeSDK::Resources::V1::Customers::Plans (readonly)

[Plans](docs.metronome.com/pricing-and-packaging/create-plans/) determine the base pricing for a customer. Use these endpoints to add a plan to a customer, end a customer plan, retrieve plans, and retrieve plan details. Create plans in the [Metronome app](app.metronome.com/plans).

Returns:



20
21
22
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 20

def plans
  @plans
end

Instance Method Details

#archive(id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerArchiveResponse

Use this endpoint to archive a customer while preserving auditability. Archiving a customer will automatically archive all contracts as of the current date and void all corresponding invoices. Use this endpoint if a customer is onboarded by mistake.

### Usage guidelines:

  • Once a customer is archived, it cannot be unarchived.

  • Archived customers can still be viewed through the API or the UI for audit purposes.

  • Ingest aliases remain idempotent for archived customers. In order to reuse an ingest alias, first remove the ingest alias from the customer prior to archiving.

  • Any notifications associated with the customer will no longer be triggered.

Parameters:

Returns:

See Also:



213
214
215
216
217
218
219
220
221
222
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 213

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

#archive_billing_configurations(customer_billing_provider_configuration_ids:, customer_id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerArchiveBillingConfigurationsResponse

Deprecate an existing billing configuration for a customer to handle churn or billing and collection preference changes. Archiving a billing configuration takes effect immediately. If there are active contracts using the configuration, Metronome will archive the configuration on the contract and immediately stop metering to downstream systems.

### Use this endpoint to:

  • Remove billing provider customer data and configurations when no longer needed

  • Clean up test or deprecated billing provider configurations

  • Free up uniqueness keys for reuse with new billing provider configurations

  • Disable threshold recharge configurations associated with archived billing providers

### Key response fields:

A successful response returns:

  • ‘success`: Boolean indicating the operation completed successfully

  • ‘error`: Null on success, error message on failure

### Usage guidelines:

  • Archiving a contract configuration during a grace period will result in the invoice not being sent to the customer

  • Automatically disables both spend-based and credit-based threshold recharge configurations for contracts using the archived billing provider

  • You can archive multiple configurations for a single customer in a single request, but any validation failures for an individual configuration will prevent the entire operation from succeeding

Parameters:

  • customer_billing_provider_configuration_ids (Array<String>) —

    Array of billing provider configuration IDs to archive

  • customer_id (String) —

    The customer ID the billing provider configurations belong to

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

Returns:

See Also:



266
267
268
269
270
271
272
273
274
275
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 266

def archive_billing_configurations(params)
  parsed, options = MetronomeSDK::V1::CustomerArchiveBillingConfigurationsParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/archiveCustomerBillingProviderConfigurations",
    body: parsed,
    model: MetronomeSDK::Models::V1::CustomerArchiveBillingConfigurationsResponse,
    options: options
  )
end

#create(name:, billing_config: nil, custom_fields: nil, customer_billing_provider_configurations: nil, customer_revenue_system_configurations: nil, external_id: nil, ingest_aliases: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerCreateResponse

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

Create a new customer in Metronome and optionally the billing configuration (recommended) which dictates where invoices for the customer will be sent or where payment will be collected.

### Use this endpoint to:

Execute your customer provisioning workflows for either PLG motions, where customers originate in your platform, or SLG motions, where customers originate in your sales system.

### Key response fields:

This end-point returns the ‘customer_id` created by the request. This id can be used to fetch relevant billing configurations and create contracts.

### Example workflow:

  • Generally, Metronome recommends first creating the customer in the downstream payment / ERP system when payment method is collected and then creating the customer in Metronome using the response (i.e. ‘customer_id`) from the downstream system. If you do not create a billing configuration on customer creation, you can add it later.

  • Once a customer is created, you can then create a contract for the customer. In the contract creation process, you will need to add the customer billing configuration to the contract to ensure Metronome invoices the customer correctly. This is because a customer can have multiple configurations.

  • As part of the customer creation process, set the ingest alias for the customer which will ensure usage is accurately mapped to the customer. Ingest aliases can be added or changed after the creation process as well.

### Usage guidelines:

For details on different billing configurations for different systems, review the ‘/setCustomerBillingConfiguration` end-point.

Parameters:

Returns:

See Also:



108
109
110
111
112
113
114
115
116
117
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 108

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

#list(customer_ids: nil, ingest_alias: nil, limit: nil, next_page: nil, only_archived: nil, salesforce_account_ids: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::CustomerDetail>

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

Gets a paginated list of all customers in your Metronome account. Use this endpoint to browse your customer base, implement customer search functionality, or sync customer data with external systems. Returns customer details including IDs, names, and configuration settings. Supports filtering and pagination parameters for efficient data retrieval.

Parameters:

  • customer_ids (Array<String>) —

    Filter the customer list by customer_id. Up to 100 ids can be provided.

  • ingest_alias (String) —

    Filter the customer list by ingest_alias

  • limit (Integer) —

    Max number of results that should be returned

  • next_page (String) —

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

  • only_archived (Boolean) —

    Filter the customer list to only return archived customers. By default, only act

  • salesforce_account_ids (Array<String>) —

    Filter the customer list by salesforce_account_id. Up to 100 ids can be provide

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

Returns:

See Also:



177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 177

def list(params = {})
  parsed, options = MetronomeSDK::V1::CustomerListParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/customers",
    query: query,
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::V1::CustomerDetail,
    options: options
  )
end

#list_billable_metrics(customer_id:, include_archived: nil, limit: nil, next_page: nil, on_current_plan: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::CustomerListBillableMetricsResponse>

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

Get all billable metrics available for a specific customer. Supports pagination and filtering by current plan status or archived metrics. Use this endpoint to see which metrics are being tracked for billing calculations for a given customer.

Parameters:

  • customer_id (String) —

    Path param

  • include_archived (Boolean) —

    Query param: If true, the list of returned metrics will include archived metrics

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

  • on_current_plan (Boolean) —

    Query param: If true, the list of metrics will be filtered to just ones that are

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

Returns:

See Also:



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 302

def list_billable_metrics(params)
  parsed, options = MetronomeSDK::V1::CustomerListBillableMetricsParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/billable-metrics", customer_id],
    query: query,
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::Models::V1::CustomerListBillableMetricsResponse,
    options: options
  )
end

#list_costs(customer_id:, ending_before:, starting_on:, limit: nil, next_page: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::CustomerListCostsResponse>

Fetch daily pending costs for the specified customer, broken down by credit type and line items. Note: this is not supported for customers whose plan includes a UNIQUE-type billable metric. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.

Parameters:

  • customer_id (String) —

    Path param

  • ending_before (Time) —

    Query param: RFC 3339 timestamp (exclusive)

  • starting_on (Time) —

    Query param: RFC 3339 timestamp (inclusive)

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

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

Returns:

See Also:



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 341

def list_costs(params)
  parsed, options = MetronomeSDK::V1::CustomerListCostsParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/costs", customer_id],
    query: query,
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::Models::V1::CustomerListCostsResponse,
    options: options
  )
end

#preview_events(customer_id:, events:, mode: nil, skip_zero_qty_line_items: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerPreviewEventsResponse

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

Preview how a set of events will affect a customer’s invoices. Generates draft invoices for a customer using their current contract configuration and the provided events. This is useful for testing how new events will affect the customer’s invoices before they are actually processed. Customers on contracts with SQL billable metrics are not supported.

Parameters:

Returns:

See Also:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 382

def preview_events(params)
  parsed, options = MetronomeSDK::V1::CustomerPreviewEventsParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: ["v1/customers/%1$s/previewEvents", customer_id],
    body: parsed,
    model: MetronomeSDK::Models::V1::CustomerPreviewEventsResponse,
    options: options
  )
end

#retrieve(customer_id:, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerRetrieveResponse

Get detailed information for a specific customer by their Metronome ID. Returns customer profile data including name, creation date, ingest aliases, configuration settings, and custom fields. Use this endpoint to fetch complete customer details for billing operations or account management.

Note: If searching for a customer billing configuration, use the ‘/getCustomerBillingConfigurations` endpoint.

Parameters:

Returns:

See Also:



135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 135

def retrieve(params)
  parsed, options = MetronomeSDK::V1::CustomerRetrieveParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s", customer_id],
    model: MetronomeSDK::Models::V1::CustomerRetrieveResponse,
    options: options
  )
end

#retrieve_billing_configurations(customer_id:, include_archived: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse

Returns all billing configurations previously set for the customer. Use during the contract provisioning process to fetch the ‘billing_provider_configuration_id` needed to set the contract billing configuration.

Parameters:

Returns:

See Also:



411
412
413
414
415
416
417
418
419
420
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 411

def retrieve_billing_configurations(params)
  parsed, options = MetronomeSDK::V1::CustomerRetrieveBillingConfigurationsParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/getCustomerBillingProviderConfigurations",
    body: parsed,
    model: MetronomeSDK::Models::V1::CustomerRetrieveBillingConfigurationsResponse,
    options: options
  )
end

#set_billing_configurations(data:, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsResponse

Create a billing configuration for a customer. Once created, these configurations are available to associate to a contract and dictates which downstream system to collect payment in or send the invoice to. You can create multiple configurations per customer. The configuration formats are distinct for each downstream provider.

### Use this endpoint to:

  • Add the initial configuration to an existing customer. Once created, the billing configuration can then be associated to the customer’s contract.

  • Add a new configuration to an existing customer. This might be used as part of an upgrade or downgrade workflow where the customer was previously billed through system A (e.g. Stripe) but will now be billed through system B (e.g. AWS). Once created, the new configuration can then be associated to the customer’s contract.

  • Multiple configurations can be added per destination. For example, you can create two Stripe billing configurations for a Metronome customer that each have a distinct ‘collection_method`.

### Delivery method options:

  • ‘direct_to_billing_provider`: Use when Metronome should send invoices directly to the billing provider’s API (e.g., Stripe, NetSuite). This is the most common method for automated billing workflows.

  • ‘tackle`: Use specifically for AWS Marketplace transactions that require Tackle’s co-selling platform for partner attribution and commission tracking.

  • ‘aws_sqs`: Use when you want invoice data delivered to an AWS SQS queue for custom processing before sending to your billing system.

  • ‘aws_sns`: Use when you want invoice notifications published to an AWS SNS topic for event-driven billing workflows.

### Key response fields:

The id for the customer billing configuration. This id can be used to associate the billing configuration to a contract.

### Usage guidelines:

Must use the ‘delivery_method_id` if you have multiple Stripe accounts connected to Metronome.

Parameters:

Returns:

See Also:



471
472
473
474
475
476
477
478
479
480
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 471

def set_billing_configurations(params)
  parsed, options = MetronomeSDK::V1::CustomerSetBillingConfigurationsParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/setCustomerBillingProviderConfigurations",
    body: parsed,
    model: MetronomeSDK::Models::V1::CustomerSetBillingConfigurationsResponse,
    options: options
  )
end

#set_ingest_aliases(customer_id:, ingest_aliases:, request_options: {}) ⇒ nil

Sets the ingest aliases for a customer. Use this endpoint to associate a Metronome customer with an internal ID for easier tracking between systems. Ingest aliases can be used in the ‘customer_id` field when sending usage events to Metronome.

### Usage guidelines:

  • This call is idempotent and fully replaces the set of ingest aliases for the given customer.

  • Switching an ingest alias from one customer to another will associate all corresponding usage to the new customer.

  • Use multiple ingest aliases to model child organizations within a single Metronome customer.

Parameters:

  • customer_id (String) —

    Path param

  • ingest_aliases (Array<String>) —

    Body param

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

Returns:

  • (nil)

See Also:



507
508
509
510
511
512
513
514
515
516
517
518
519
520
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 507

def set_ingest_aliases(params)
  parsed, options = MetronomeSDK::V1::CustomerSetIngestAliasesParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: ["v1/customers/%1$s/setIngestAliases", customer_id],
    body: parsed,
    model: NilClass,
    options: options
  )
end

#set_name(customer_id:, name:, request_options: {}) ⇒ MetronomeSDK::Models::V1::CustomerSetNameResponse

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

Updates the display name for a customer record. Use this to correct customer names, update business names after rebranding, or maintain accurate customer information for invoicing and reporting. Returns the updated customer object with the new name applied immediately across all billing documents and interfaces.

Parameters:

  • customer_id (String) —

    Path param

  • name (String) —

    Body param: The new name for the customer. This will be truncated to 160 charact

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

Returns:

See Also:



542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 542

def set_name(params)
  parsed, options = MetronomeSDK::V1::CustomerSetNameParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: ["v1/customers/%1$s/setName", customer_id],
    body: parsed,
    model: MetronomeSDK::Models::V1::CustomerSetNameResponse,
    options: options
  )
end

#update_config(customer_id:, leave_stripe_invoices_in_draft: nil, salesforce_account_id: nil, request_options: {}) ⇒ nil

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

Update configuration settings for a specific customer, such as external system integrations (e.g., Salesforce account ID) and other customer-specific billing parameters. Use this endpoint to modify customer configurations without affecting core customer data like name or ingest aliases.

Parameters:

  • customer_id (String) —

    Path param

  • leave_stripe_invoices_in_draft (Boolean, nil) —

    Body param: Leave in draft or set to auto-advance on invoices sent to Stripe. Fa

  • salesforce_account_id (String, nil) —

    Body param: The Salesforce account ID for the customer

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

Returns:

  • (nil)

See Also:



578
579
580
581
582
583
584
585
586
587
588
589
590
591
 
# File 'lib/metronome_sdk/resources/v1/customers.rb', line 578

def update_config(params)
  parsed, options = MetronomeSDK::V1::CustomerUpdateConfigParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: ["v1/customers/%1$s/updateConfig", customer_id],
    body: parsed,
    model: NilClass,
    options: options
  )
end