Custom field definitions extend the data model of core entities (customers, subscriptions, plans, products) with your own fields. Define the field type, validation rules, and visibility, then set values on individual records.
Supported field types: text, number, boolean, date, enum, entity_ref
Key concepts:
- Entity types - which resources this field applies to (e.g.,
customer,subscription) - Field group - logical grouping for UI display
- Validation - regex patterns, min/max values, required/optional
- Auditable - whether changes to this field are tracked in the audit log
- Deprecation - soft-disable a field before permanent removal
List custom field definitions
Lists custom field definitions. Supports the unified field.op=value filter grammar (status, field_type, field_group, key, visibility, write_access, auditable, created_at, updated_at, deprecated_at) plus an entity_type control parameter that scopes the list to definitions targeting a given entity (CUSTOMER, PRODUCT, …).
query Parameters
entity_typeFilter by entity type (CUSTOMER, PRODUCT, PLAN, …)
statusFilter by status (e.g. status=active or status.in=active,deprecated)
field_typeFilter by field type (e.g. field_type.in=string,number)
field_groupFilter by field group
keyFilter by key (supports .contains)
List custom field definitions › Responses
List wrapped in data envelope
auditablecreated_atdefault_valuedeleted_atdeprecated_atdescriptiondisplay_nameentity_typesfield_groupfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessCreate a custom field definition
Creates a new custom field definition for the organization
Create a custom field definition › Request Body
auditabledefault_valuedescriptiondisplay_nameentity_typesfield_groupfield_typekeyshow_in_tablesort_ordervisibilitywrite_accessCreate a custom field definition › Responses
Wrapped in data envelope
auditablecreated_atdefault_valuedeleted_atdeprecated_atdescriptiondisplay_nameentity_typesfield_groupfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessGet a custom field definition
Returns a single custom field definition by ID
path Parameters
idCustom Field Definition UUID
Get a custom field definition › Responses
Wrapped in data envelope
auditablecreated_atdefault_valuedeleted_atdeprecated_atdescriptiondisplay_nameentity_typesfield_groupfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessUpdate a custom field definition
Partially updates an existing custom field definition
path Parameters
idCustom Field Definition UUID
Update a custom field definition › Request Body
auditabledefault_valuedescriptiondisplay_nameexpected_versionfield_groupshow_in_tablesort_orderstatusvisibilitywrite_accessUpdate a custom field definition › Responses
Wrapped in data envelope
auditablecreated_atdefault_valuedeleted_atdeprecated_atdescriptiondisplay_nameentity_typesfield_groupfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessDeprecate a custom field definition
Transitions a custom field definition to deprecated status
path Parameters
idCustom Field Definition UUID
Deprecate a custom field definition › Responses
Wrapped in data envelope
auditablecreated_atdefault_valuedeleted_atdeprecated_atdescriptiondisplay_nameentity_typesfield_groupfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessPurge a custom field definition
Hard-deletes the definition and all associated values. Requires X-Confirm-Purge: true header for safety.
path Parameters
idCustom Field Definition UUID
Headers
X-Confirm-PurgeMust be 'true' to confirm purge
Purge a custom field definition › Responses
Purge result wrapped in data envelope