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

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

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:



171
172
173
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 171

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:



47
48
49
50
51
52
53
54
55
56
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 47

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:



73
74
75
76
77
78
79
80
81
82
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 73

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:



100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 100

def list_keys(params = {})
  parsed, options = MetronomeSDK::V1::CustomFieldListKeysParams.dump_request(params)
  query_params = [:next_page]
  @client.request(
    method: :post,
    path: "v1/customFields/listKeys",
    query: parsed.slice(*query_params),
    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:



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 128

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:



157
158
159
160
161
162
163
164
165
166
 
# File 'lib/metronome_sdk/resources/v1/custom_fields.rb', line 157

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