openapi: 3.0.1
info:
  title: Metronome Alerts Custom fields API
  version: 1.0.0
  description: '[Alerts](https://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.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
  description: Production server
security:
- bearerAuth: []
tags:
- name: Custom fields
  description: '[Custom fields](https://docs.metronome.com/integrations/custom-fields/) enable adding additional data to Metronome entities. Use these endpoints to create, retrieve, update, and delete custom fields.'
paths:
  /v1/customFields/addKey:
    post:
      description: "Creates a new custom field key for a given entity (e.g. billable metric, contract, alert).\n\nCustom 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.\n\n### Use this endpoint to:\n- 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. \n- 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. \n\n### Usage guidelines:\n- 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`\n- Custom fields set on products can be used in the Stripe integration to set metadata on invoices.\n- Custom fields for customers, contracts, invoices, products, commits, scheduled charges, and subscriptions are passed down to the invoice.\n"
      operationId: addCustomFieldKey-v1
      summary: Create a custom field key
      tags:
      - Custom fields
      requestBody:
        description: Add a key to the allow list for an entity
        content:
          application/json:
            schema:
              type: object
              required:
              - entity
              - key
              - enforce_uniqueness
              properties:
                entity:
                  $ref: '#/components/schemas/ManagedEntity'
                key:
                  type: string
                enforce_uniqueness:
                  type: boolean
            example:
              entity: customer
              key: x_account_id
              enforce_uniqueness: true
      responses:
        '200':
          description: Success
  /v1/customFields/removeKey:
    post:
      description: '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.

        '
      operationId: disableCustomFieldKey-v1
      summary: Delete a custom field key
      tags:
      - Custom fields
      requestBody:
        description: Remove a key from the allow list for an entity
        content:
          application/json:
            schema:
              type: object
              required:
              - entity
              - key
              properties:
                entity:
                  $ref: '#/components/schemas/ManagedEntity'
                key:
                  type: string
            example:
              entity: customer
              key: x_account_id
      responses:
        '200':
          description: Success
  /v1/customFields/setValues:
    post:
      description: '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.

        '
      operationId: setCustomFields-v1
      summary: Set custom field values
      tags:
      - Custom fields
      requestBody:
        description: The custom field values to set
        content:
          application/json:
            schema:
              type: object
              required:
              - entity
              - entity_id
              - custom_fields
              properties:
                entity:
                  $ref: '#/components/schemas/ManagedEntity'
                entity_id:
                  type: string
                  format: uuid
                custom_fields:
                  $ref: '#/components/schemas/CustomField'
            example:
              entity: customer
              entity_id: 99594816-e8a5-4bca-be21-8d1de0f45120
              custom_fields:
                x_account_id: KyVnHhSBWl7eY2bl
      responses:
        '200':
          description: Success
  /v1/customFields/deleteValues:
    post:
      description: '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.

        '
      operationId: deleteCustomFields-v1
      summary: Delete custom fields
      tags:
      - Custom fields
      requestBody:
        description: Delete one or more custom fields
        content:
          application/json:
            schema:
              type: object
              required:
              - entity
              - entity_id
              - keys
              properties:
                entity:
                  $ref: '#/components/schemas/ManagedEntity'
                entity_id:
                  type: string
                  format: uuid
                keys:
                  type: array
                  items:
                    type: string
            example:
              entity: customer
              entity_id: 99594816-e8a5-4bca-be21-8d1de0f45120
              keys:
              - x_account_id
      responses:
        '200':
          description: Success
  /v1/customFields/listKeys:
    post:
      description: '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.

        '
      operationId: listCustomFieldKeys-v1
      summary: List custom field keys
      parameters:
      - $ref: '#/components/parameters/NextPage'
      tags:
      - Custom fields
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entities:
                  type: array
                  description: Optional list of entity types to return keys for
                  items:
                    $ref: '#/components/schemas/ManagedEntity'
            example:
              entities:
              - customer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_page
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - entity
                      - key
                      - enforce_uniqueness
                      properties:
                        entity:
                          $ref: '#/components/schemas/ManagedEntity'
                        key:
                          type: string
                        enforce_uniqueness:
                          type: boolean
                  next_page:
                    type: string
                    nullable: true
              example:
                data:
                - entity: customer
                  key: x_account_id
                  enforce_uniqueness: true
                next_page: null
components:
  schemas:
    ManagedEntity:
      type: string
      enum:
      - alert
      - billable_metric
      - charge
      - commit
      - contract_credit
      - contract_product
      - contract
      - customer
      - discount
      - invoice
      - professional_service
      - product
      - rate_card
      - scheduled_charge
      - subscription
      - package_commit
      - package_credit
      - package_subscription
      - package_scheduled_charge
      x-mint-enum:
        professional_service:
        - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2
    CustomField:
      type: object
      description: 'Custom fields to be added eg. { "key1": "value1", "key2": "value2" }'
      additionalProperties:
        type: string
  parameters:
    NextPage:
      name: next_page
      in: query
      description: Cursor that indicates where the next page of results should start.
      required: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer