Custom fields: overview
InBlack has two separate custom-field systems. They solve different problems and do not synchronize.
Substrate custom fields
Substrate fields extend a supported record type across its pillar. Examples include a referred_by field on contacts or a warehouse_zone field on products.
The current physical types are contacts, companies, activities, orders, products, fulfillments, and marketing campaigns. Their declarations are tenant-scoped, versioned, and validated when values are written.
There is no dedicated operator page for declaring substrate fields today. An authorized integration can manage the schema through the entity-schema HTTP endpoint, and agents can edit record values with inblack_update_record after a field exists.
Commerce product-group definitions
Commerce also has product-group field definitions in its own catalog UI. These definitions describe product attributes for a product group and use Commerce-owned storage and types.
Use this system when the field belongs to one product group’s merchandising model. Manage it in the Commerce product-group field-definition workflow.
Choose the right system
| Need | System |
|---|---|
| Add data to contacts, companies, activities, orders, products, fulfillments, or campaigns | Substrate |
| Define product attributes for a specific product group | Commerce product-group definitions |
| Query or update a substrate value through an agent | inblack_query_records / inblack_update_record |
| Manage a product group’s catalog fields in the UI | Commerce field definitions |
There is no migration or synchronization path between the two systems. A similarly named field in each system remains two independent declarations and two independent values.
Before adding a field, confirm that a native field does not already represent the data. Native fields have the strongest product support and reporting semantics.