Overview

Every organisation starts with the built-in data model: products, orders, contacts and the rest. Custom entities let you add your own tables to it, and custom fields add your own columns to any table, built-in or custom. A custom entity behaves like a built-in one: it has a grid, an editor, filters, history, changesets and an API, and the AI assistant can read it.

Both are managed by organisation administrators in Settings → Customization:

[navigate:/customEntities|Custom entities|database] [navigate:/customFields|Custom fields|columns]

Changes apply to the database immediately after you save a definition. There is no deployment step.

Custom Entities

A custom entity is a new table. Create one with:

• Name – shown in menus and titles, translatable. The plural name is used for the grid, the singular name for the editor.
• Key – the technical name used in filters, the API and imports. It is derived from the name while you type and always starts with x_ (for example x_cars). The key cannot be changed once the entity exists.
• Icon and category – where the entity appears in the left menu. Entities without a category are listed under Customization.
• Primary fields – the fields shown by default in the grid and used as the record title.
• Default order – the columns the grid is sorted by until the user picks an order; click the arrow on a column to switch between ascending and descending.
• Description – a short note for users and for the AI assistant.

The editor of an entity lists its fields. Add a field there and the entity is filled in for you; the primary fields and default order pickers offer the fields once the entity was saved.

Every custom entity automatically gets an id, created and updated timestamps, a history of changes and support for changesets and locks. You do not need to define these.

After saving, the entity appears in the left menu. Open it to add records like in any other grid, or import them through the import engine using the entity key.

Custom Fields

A custom field is a new column on a table. Pick the entity first (a built-in one such as Products, or one of your custom entities), then:

• Name – the column label, translatable.
• Key – derived from the name, always prefixed with x_ (for example x_colour). Fixed once the field exists.
• Type – text, long text, HTML, number, money, integer, yes/no, date, date and time, enumeration, relation, URL, e-mail, telephone, colour, image or JSON.
• Translatable – text fields can hold a value per language, like the built-in product name.

The editor only shows the options that make sense for the chosen type:

Fields can be grouped in the editor with Group, ordered with Order, and indexed with Create index when you filter on them often.

Relations between custom entities

A relation field stores a link to one record of another entity (for example a Car belongs to a Brand). The other side automatically gets a list of linked records (the brand shows its cars). Mark the field as owned when the records belong to their parent and should be shown inline in its editor, like order lines.

A many-to-many relation (a Car can have many Features and a Feature applies to many Cars) is modelled with a small custom entity in the middle that holds two relation fields, one marked as the source and one as the destination of the relation.

Enabling a Hidden Built-in Field

The built-in model contains more fields than your edition shows. For example, fields that only exist in a connected accounting system are hidden for a plain e-shop organisation. If you need such a field, you do not have to create a custom one: create a custom field with Kind = Native and enter the key of the built-in field. The column is created in your database and the field appears in grids, editors and filters with its standard name, translations and behaviour.

Prefer a native field over a custom one whenever a built-in field exists for the same purpose. It keeps your data compatible with integrations and with other organisations.

Deleting and Purging

Definitions are never deleted directly, because the data in the column or table would be lost. Instead:

1. Set the status of the entity or field to To delete. It disappears from menus, grids and editors, but the data stays in the database.
2. Change the status back to Active if it was a mistake. Nothing was lost.
3. An administrator can later purge the definition, which drops the column or table for good.

Addons

Addons from the marketplace can ship their own custom entities and fields. They are installed into your organisation when you activate the addon and marked To delete when you deactivate it. Such definitions are managed by the addon and cannot be edited.

Limits and Good Practice

• Up to about 100 custom entities per organisation and 200 fields per entity.
• Keys are permanent. Choose them carefully; names and labels can be changed any time.
• Use the built-in entities and native fields where they fit. Custom entities are for data the platform has no place for.
• Custom data is included in exports, filters, dashboards and the API like any other data. In the Query API, address it by its key, for example x_cars { x_name, x_brand { name } }.

[navigate:/help/en/api/query|Query API|code]