Class: MetronomeSDK::Resources::V1::CustomFields

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

Overview

[Custom fields](docs.metronome.com/integrations/custom-fields/) enable adding additional data to Metronome entities. Use these endpoints to create, retrieve, update, and delete custom fields.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ CustomFields

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

Parameters:



175
176
177
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 175

def initialize(client:)
  @client = client
end

Instance Method Details

#add_key(enforce_uniqueness:, entity:, key:, request_options: {}) ⇒ nil

Creates a new custom field key for a given entity (e.g. billable metric, contract, alert).

Custom fields are properties that you can add to Metronome objects to store metadata like foreign keys or other descriptors. This metadata can get transferred to or accessed by other systems to contextualize Metronome data and power business processes. For example, to service workflows like revenue recognition, reconciliation, and invoicing, custom fields help Metronome know the relationship between entities in the platform and third-party systems.

### Use this endpoint to:

  • Create a new custom field key for Customer objects in Metronome. You can then use the Set Custom Field Values endpoint to set the value of this key for a specific customer.

  • Specify whether the key should enforce uniqueness. If the key is set to enforce uniqueness and you attempt to set a custom field value for the key that already exists, it will fail.

### Usage guidelines:

  • Custom fields set on commits, credits, and contracts can be used to scope alert evaluation. For example, you can create a spend threshold alert that only considers spend associated with contracts with custom field key ‘contract_type` and value `paygo`

  • Custom fields set on products can be used in the Stripe integration to set metadata on invoices.

  • Custom fields for customers, contracts, invoices, products, commits, scheduled charges, and subscriptions are passed down to the invoice.

Parameters:

Returns:

  • (nil)

See Also:



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 50

def add_key(params)
  parsed, options = MetronomeSDK::V1::CustomFieldAddKeyParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/customFields/addKey",
    body: parsed,
    model: NilClass,
    options: options
  )
end

#delete_values(entity:, entity_id:, keys:, request_options: {}) ⇒ nil

Remove specific custom field values from a Metronome entity instance by specifying the field keys to delete. Use this endpoint to clean up unwanted custom field data while preserving other fields on the same entity. Requires the entity type, entity ID, and array of keys to remove.

Parameters:

Returns:

  • (nil)

See Also:



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 76

def delete_values(params)
  parsed, options = MetronomeSDK::V1::CustomFieldDeleteValuesParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/customFields/deleteValues",
    body: parsed,
    model: NilClass,
    options: options
  )
end

#list_keys(next_page: nil, entities: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPageWithoutLimit<MetronomeSDK::Models::V1::CustomFieldListKeysResponse>

Retrieve all your active custom field keys, with optional filtering by entity type (customer, contract, product, etc.). Use this endpoint to discover what custom field keys are available before setting values on entities or to audit your custom field configuration across different entity types.

Parameters:

Returns:

See Also:



103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 103

def list_keys(params = {})
  query_params = [:next_page]
  parsed, options = MetronomeSDK::V1::CustomFieldListKeysParams.dump_request(params)
  query = MetronomeSDK::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :post,
    path: "v1/customFields/listKeys",
    query: query,
    body: parsed.except(*query_params),
    page: MetronomeSDK::Internal::CursorPageWithoutLimit,
    model: MetronomeSDK::Models::V1::CustomFieldListKeysResponse,
    options: options
  )
end

#remove_key(entity:, key:, request_options: {}) ⇒ nil

Removes a custom field key from the allowlist for a specific entity type, preventing future use of that key across all instances of the entity. Existing values for this key on entity instances will no longer be accessible once the key is removed.

Parameters:

Returns:

  • (nil)

See Also:



132
133
134
135
136
137
138
139
140
141
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 132

def remove_key(params)
  parsed, options = MetronomeSDK::V1::CustomFieldRemoveKeyParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/customFields/removeKey",
    body: parsed,
    model: NilClass,
    options: options
  )
end

#set_values(custom_fields:, entity:, entity_id:, request_options: {}) ⇒ nil

Sets custom field values on a specific Metronome entity instance. Overwrites existing values for matching keys while preserving other fields. All updates are transactional—either all values are set or none are. Custom field values are limited to 200 characters each.

Parameters:

Returns:

  • (nil)

See Also:



161
162
163
164
165
166
167
168
169
170
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 161

def set_values(params)
  parsed, options = MetronomeSDK::V1::CustomFieldSetValuesParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/customFields/setValues",
    body: parsed,
    model: NilClass,
    options: options
  )
end