Update a custom field definition

PATCH /v1/custom-metadata-definitions/{id}

Update a custom field definition

The key is immutable: it is both the jsonb key and the identity a routing rule stores, so renaming it would need a value rewrite plus AST rewrites. Label, unit, type and enum values are all editable.

Requires: routing.manage

Path Parameters

id required

string

Request Body

UpdateCustomMetadataDefinitionRequest

clearIncompatibleValuesoptional

boolean

defaultToNowoptional

boolean

defaultValueoptional

string | number | boolean

enumValuesoptional

string[]

labeloptional

string

unitoptional

string

valueTypeoptional

any

Example Request

application/json

{
  "label": "string",
  "defaultToNow": true,
  "clearIncompatibleValues": true
}

Response Schema

CustomMetadataDefinition

createdAtrequired

string

format: date-time

defaultToNowrequired

boolean

Date/time fields only, and the only default they can carry: the value is the moment the record was created. A fixed date is almost never the right default, and there is no way to express "now" as a literal.

defaultValuerequired

string | number | boolean

Written into a record's `customMetadata` when that record is created, so the field is on every new record of its type. This is the only way a definition puts itself on a record: a field with no value is not listed, because a row the record does not carry is a row that lies about it. Never applied to records that already exist.

entityTyperequired

any

enumValuesrequired

string[]

idrequired

string

pattern: ^[a-z0-9]{24}$

keyrequired

string

labelrequired

string

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

unitrequired

string

updatedAtrequired

string

format: date-time

valueTyperequired

any

Example Response

200 OK — application/json

{
  "key": "string",
  "label": "string",
  "defaultToNow": true,
  "id": "string",
  "storeId": "string",
  "createdAt": "2026-09-13T00:32:48.554Z",
  "updatedAt": "2026-09-13T00:32:48.554Z"
}