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, …)
Filter by entity type (CUSTOMER, PRODUCT, PLAN, …)
statusFilter by status (e.g. status=active or status.in=active,deprecated)
Filter by status (e.g. status=active or status.in=active,deprecated)
field_typeFilter by field type (e.g. field_type.in=string,number)
Filter by field type (e.g. field_type.in=string,number)
field_groupFilter by field group
Filter by field group
keyFilter by key (supports .contains)
Filter by key (supports .contains)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List custom field definitions › Responses
OK
Create a custom field definition
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a custom field definition › Request Body
auditabledefault_valuedescriptiondisplay_nameentity_typesfield_groupfield_typekeyshow_in_tablesort_ordervisibilitywrite_accessCreate a custom field definition › Responses
Created
Get a custom field definition
path Parameters
idCustom field definition UUID
Custom field definition UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a custom field definition › Responses
OK
Update a custom field definition
Partially updates an existing custom field definition.
path Parameters
idCustom field definition UUID
Custom field definition UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a custom field definition › Request Body
auditabledefault_valuedescriptiondisplay_nameexpected_versionfield_groupshow_in_tablesort_orderstatusvisibilitywrite_accessUpdate a custom field definition › Responses
OK
Archive a custom field definition
Soft-deletes the custom field definition.
path Parameters
idCustom field definition UUID
Custom field definition UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Archive a custom field definition › Responses
No Content
Deprecate a custom field definition
Transitions a custom field definition to deprecated status.
path Parameters
idCustom field definition UUID
Custom field definition UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Deprecate a custom field definition › Responses
OK
Purge 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
Custom field definition UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Confirm-PurgeMust be 'true' to confirm purge
Must be 'true' to confirm purge
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Purge a custom field definition › Responses
OK