Add custom fields

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 in Stripe, custom fields help Metronome know the relationship between entities in the platform and third-party systems.

How custom fields work

You can add custom fields to most Metronome entities: customer, product, contract, commit, credit, scheduled charge, rate card, and alert. These fields are persisted across the platform and can be fetched in the UI, API, and data export wherever the object appears.

When deciding when to create custom fields and where to put them, it’s important to think through the relationship of entities between a given external system and Metronome. For example, to model a NetSuite ERP integration in Metronome, you want to identify what the counterpart is for each object that you want to sync. Frequently, clients sync Metronome invoices to NetSuite and attach the invoices to the related NetSuite customer ID. To store the relationship between them, create a custom field called netsuite_customer_id on the Metronome customer object. This field enables a user to query the customer object and determine the foreign key mapping between the two systems.

The next example walks through how to associate a line item to a product ID (or SKU) in Stripe by adding a custom field called stripe_product_id to the Metronome product.

Create a custom field

You can create a custom field using the Metronome app or API.

To create a custom field on a product 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 modal, select Product (Contracts) for entity, enter stripe_product_id for the Key, and turn on the Unique values required.
5. Click Save.

caution

Enforcing unique values limits the ability to set the same value across multiple objects.

Use this to map foreign entities that have a one-to-one relationship with a Metronome object. Uniqueness is enforced even when an object is archived. To resolve a duplicate issue with an archived object, reset the value of the field.

To create a custom field with the API, make a POST request to /customFields/addKey. The endpoint takes three parameters, all required:

• entity
• key
• enforce_uniqueness

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

Set a custom field value

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

To set a custom field value in the Metronome app:

1. Go to the the Contract Pricing page and find the product on the Product List.
2. Click on the product record to open the drawer containing the product metadata.
3. Click the overflow button in the top right corner of the drawer and click Manage custom fields.
4. Within customer settings, click Custom fields —> Manage.
5. Within the custom fields page, click Set custom field.
6. In the resulting modal, select the field name and provide the field value.
7. Click Save.

To set a custom field value with 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 product, adding the corresponding stripe_product_id value:

curl https://api.metronome.com/v1/customFields/setValues \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "contract_product",
    "entity_id": "76e57c3a-064f-49ad-8740-2bff58f2f808",
    "custom_fields": {
      "stripe_product_id": "prod_KyVnHhSBWl7eY2bl"
    }
  }'

Alternatively, you can set a custom field value on the creation of an object. For example, to set a custom field value on the contract object, you could do this within the POST request to the /createContract endpoint.

Fetch a custom field value

Once you set a custom field value on an object instance (like a product), the value gets returned when you request that object, including in the Metronome app, API calls, and data exports.

As an example, consider the invoice response. Given that products in Metronome map to line items on invoices, the stripe_product_id custom field propagates to its associated line item. This mapping enables Metronome to link line items to Stripe products when creating invoices in Stripe. Here’s an example invoice payload:

{
  "data": {
    "id": "09abf41e-2e68-622f-93bc-ce8ef21215de",
    "issued_at": "2024-09-02T00:00:00+00:00",
    "start_timestamp": "2024-08-01T00:00:00+00:00",
    "end_timestamp": "2024-09-01T00:00:00+00:00",
    "customer_id": "195826717-122e-5150-a96e-ab7ef9744e9c",
    "customer_custom_fields": {},
    "type": "USAGE",
    "credit_type": {
      "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
      "name": "USD (cents)"
    },
    "status": "DRAFT",
    "total": 22000,
    "external_invoice": null,
    "contract_id": "ccffadcf-5e3b-407d-8c5e-3f678508bfd1",
    "contract_custom_fields": {},
    "line_items": [
      {
        "product_id": "d3d10cd4-e234-4265-91c1-a95f09e6a69c",
        "product_type": "UsageProductListItem",
        "product_custom_fields": {
          "stripe_product_id": "prod_KyVnHhSBWl7eY2bl"
        },
        "name": "Usage Product",
        "total": 22000,
        "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
        },
        "starting_at": "2024-08-01T00:00:00+00:00",
        "ending_before": "2024-09-01T00:00:00+00:00",
        "unit_price": 110,
        "quantity": 200
      },
      ...
    ]
  }
 }