API ReferenceCustom Field Definitions

Create Custom Field Definition

View as Markdown

Create a new custom field definition.

Defines a new custom field schema for a specific entity type. Once created, values can be set on entities of that type using the field_key.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.
field_keystringRequired2-64 characters

Unique key for this field. Must start with a letter, contain only lowercase letters, numbers, underscores, and dashes (2-64 chars). This key is used when setting values on entities.

entity_typeenumRequired

The entity type this field applies to (customer, subscription, product, price, invoice, checkout_session)

data_typeenumRequired

The data type for values: text (max 500 chars), number (integer or decimal), boolean, or select (from predefined options)

display_namestringRequired1-255 characters

Human-readable name for the field, shown in the dashboard

descriptionstring or nullOptional
Optional description explaining the field's purpose
constraintsmap from strings to any or nullOptional

Type-specific constraints. For number: {min, max}. For select: {options: [‘a’, ‘b’]}. Text and boolean do not support constraints.

is_visible_in_listbooleanOptionalDefaults to true
Whether this field appears as a column in list views. Defaults to true.

Response

Successful Response
idstring

Unique identifier for the definition (e.g., ‘cfd_dev_abc123’)

field_keystring
The key used when setting values on entities
entity_typeenum
The entity type this field applies to
data_typeenum
The data type for values
display_namestring

Human-readable name for the field

is_visible_in_listboolean
Whether this field appears as a column in list views
created_atdatetime
When the definition was created
updated_atdatetime
When the definition was last updated
descriptionstring or nullOptional
Optional description of the field
constraintsmap from strings to any or nullOptional

Type-specific constraints

Errors

422
Unprocessable Entity Error