Create custom fields

Metronome has a versatile API designed to work seamlessly with a range of integrations. Out-of-the-box, Metronome structures its core data types to pass necessary information to third parties.

To take full advantage of your integrations, we support custom fields on Metronome entities: customers, products, and so forth. Custom fields allow you to add to your Metronome data any extra information necessary to improve the interoperability of your tech stack.

How custom fields work

Custom fields can be added to every critical Metronome entity: Charge, Credit Grant, Customer, Customer Plan, Invoice (objects), and Product. You then add values for these custom field keys on specific instances of the entity (on a specific Customer or Charge). For example, you can add a Salesforce ID to the Customer entity, allowing you to add that information to every Customer record.

The values of custom fields are included when you fetch entities through the API, view them in the Metronome app, or export data.

1. Create the custom field

Custom fields can be created using the Metronome app or API. To create a custom field in the Metronome app:

1. Click General settings.
2. Within settings, click the Custom fields tab.
3. Within custom fields, click Add new field key.
4. In the resulting model, select the entity, provide the key name, and turn on the Unique values required as appropriate.
5. Click Save.

For the API, make a POST request to /customFields/addKey. The endpoint takes three parameters, all required:

• entity
• key
• enforce_uniqueness

Set enforce_uniqueness to true for values that are unique in the external system. This extra check prevents you from having duplicate records in Metronome.

This request adds an x_account_id field to the Customer entity:

curl https://api.metronome.com/v1/customFields/addKey \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customer",
    "key": "x_account_id",
    "enforce_uniqueness": true
  }'

2. Set a custom field value

Once you've defined a custom field on an entity, you can set values for that field on individual entity instances. Again, this can be done using the Metronome app or API.

To set a custom field value in the Metronome app:

1. Find the customer on the Customers page.
2. Click on the customer record to bring up the customer details page.
3. Within the customer details page, click Settings.
4. Within customer settings, click Manage under Custom fields.
5. Within the custom fields page, click Set custom field.
6. In the resulting model, select the field name and provide the field value.
7. Click Save.

For the API, make a POST request to /customFields/setValues. The endpoint takes three parameters, all required:

• entity
• entity_id
• custom_fields

The custom_fields parameter accepts an array of key-value pairs, allowing you to set multiple custom field values—on a single entity instance—in one API call.

This request updates a specific customer, adding the corresponding x_account_id value:

curl https://api.metronome.com/v1/customFields/setValues \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "customer",
    "entity_id": "99594816-e8a5-4bca-be21-8d1de0f45120",
    "custom_fields": {
      "x_account_id": "KyVnHhSBWl7eY2bl"
    }
  }'

Provide custom field values on updates

You can only set a custom field value by updating an existing Charge, Customer, and so on. You cannot set the custom field value when creating the instance.

3. Fetch a custom field value

One a custom field value is set on an entity instance (such as a customer), the value is returned wherever that entity is requested, including the Metronome app, API calls, and data exports.

To view custom field values through the API, look at the returned custom_fields hash:

{
  "data": {
    "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "external_id": "team@example.com",
    ...
    "custom_fields": {
      "x_account_id": "KyVnHhSBWl7eY2bl"
    }
  }
} 

To view custom field values in the Metronome app, follow the above steps for setting a value. You'll see the custom field value on the Manage custom fields page.

info

You can view all the custom fields you've defined using the list custom fields API endpoint or the General settings > Custom fields pane of the Metronome app.