What is a custom field?
Custom fields are a powerful feature in e-commerce platforms, allowing for greater flexibility and the ability to tailor the platform to meet specific business requirements.
A custom field is a user-defined data field that allows users to capture and store information specific to their business needs or preferences. These fields are not predefined by the system but can be created, named and configured by users to capture unique information relevant to their operations. They provide flexibility in storing and organizing data beyond standard fields, allowing for more comprehensive and personalized record-keeping.
Custom fields can be added to a product, company, customer, profile, order, or other entities within the platform to capture specific information that is not covered by the standard fields.
Where can custom fields be found and managed?
Custom fields can be found in the principal Menu —> Settings —> Custom Fields
There are three entities in which you can create or edit custom fields: Product, Product Variant and Company.
Product: refers to tangible or intangible item that are offered for sale or use by a company. It could be a physical object, such as a smartphone or a book, or a digital service, such as software or a subscription. Products have distinct characteristics, features, and functionalities that fulfill specific needs or desires of customers. In the context of your backoffice, a product would likely contain information such as product name, price, category, and any other relevant details.
Product Variant: is a specific version or variation of a product that shares some similarities with the original product but may differ in certain attributes, such as size, color, configuration, or packaging. Product variants are often used to offer customers more choices and cater to different preferences or requirements without having to create entirely separate products.
Company: A company is a legal entity formed by a group of individuals to carry out business activities, such as manufacturing, trading, or providing services, with the aim of generating profits. In the context of your backoffice, a company entity would represent your organization and would contain information such as company name, address, contact details, tax identification number, and any other relevant company-specific data.
On the main screen, you can see a resume of all the custom fields created and their characteristics: the name (field), the entity to which it belongs (field scope), and if it's a required field or not. When accessing them, you can see their characteristics (name, ID, type and value). You can also edit or delete the custom field by clicking on the icons off the right of this screen. To see detailed information about this, go to the “creating custom fields” section.
There is also a search tool where you can find an existing custom field more easily by its name or by its ID.
Who can edit custom fields?
It's important to define user access permissions to ensure only authorized personnel can modify custom fields.
In the backoffice every tenant can define and configure roles and permissions according to the company's needs. There is a Roles and Permission feature to do this.
The backoffice, as a default option, only permits that “owner” users to get, create, update and remove a custom field.
Creating custom fields
A user can add a custom field in any of the existing entities: Product, Product Variant and Company. A custom field can only belong to one entity.
In the backoffice the maximum amount that allows the creation of custom fields is 50.
To add a new custom field user would need to define and enter the information on the next fields types:
- Custom field name : craft a descriptive name that identifies easily your custom field
- ID: it is necessary to include a unique ID that can be found in the API and permits seamless integration. It is recommended to put the name of the ID with no spaces and with the special character (-) if it's a compound name, for example: origin-country, minimum-billing-amount.
- Field Scope: define the field scope to specify the precise areas or entity where the custom field applies, e.g Product or Product variant. It is important to take into consideration that a custom field can only belong to one entity
- Field type: It is important to select the ideal field type depending on the desired collection of your data. There are nine different types: alphanumeric, number, text, rich text, boolean dropdown, money, image, file.
- Default value: the API needs to receive the “value” field with a specific format when creating any custom field. The value is ALWAYS a string, but, this string, must have a specific format depending on the custom field type we are referring to.
- Required field: decide if the field is required for essential information or not. If a field is created and marked as required, this should trigger updates across all contexts. Default value of the custom field is essential for this step. After defining value, all existing companies should be updated to the default value.
Field Types :
Here you can find a more detailed explanation of each field type and their default value characteristics so you can enter the data in the correct format.
Alphanumeric:
Refers to data fields that can accept both letters (alphabetic characters) and numbers (numeric characters). These fields allow users to input and store alphanumeric data, which can include a combination of letters, numbers, and special characters such as punctuation marks or symbols. Alphanumerical custom fields are versatile and commonly used to capture information such as names, addresses, product codes, identification numbers.
The format to enter the default value is text and integers, for example: “Palau_Mar 21”
Number:
Refers to data fields that specifically accept numerical values.These fields are designed to store numeric data, such as integers or floating-point numbers, allowing users to input and manipulate numerical information. This type is commonly used for capturing quantitative data, including quantities, measurements, financial figures, percentages, and other numerical values relevant to the user's requirements.
The format to enter the default value is integers, for example :”132”
Text:
Refers to data fields that are designed to store and handle textual information. These fields allow users to input and store arbitrary text data, including letters, symbols, and special characters. Text fields are versatile and can accommodate various forms of textual content, such as names, descriptions, comments, and other free-form text entries.
The format to enter the default value is a JSON object, according to object (list<string, string>). These objects often have a collection of attributes that define their properties and relationships with other objects. JSON is a structure to represent data. JSON objects are collections of key-value pairs, where keys are strings and values can be strings, numbers, boolean, arrays, other JSON objects, or null.
It is a translatable object. The standard format is usually lowercase for the language code and uppercase for the country code, separated by an underscore:
For example:
{
”es_ES”: "Bienvenidos a la empresa”,
“en_GB”: “Welcome to the company”
}
Rich Text:
Refers to a type of data field that allows users to input and store formatted text content. Unlike plain text fields, which only support unformatted text, rich text fields enable the application of various text formatting options such as header types, font sizes, bulleted or numbered lists, and even embedded hyperlinks.
The format to enter the default value is a JSON object, according to object (list<string, string>)
It is a translatable object. The standard format is usually lowercase for the language code and uppercase for the country code, separated by an underscore, for example:
{
”es_ES”: “<p>**Bienvenidos** <b>**a**</b> **la empresa**</p>”,
“en_GB”: “<p>**Welcome** <b><**to the company**</b><p>”
}
Boolean:
Refers to a type of data field that stores binary data. They are commonly used for capturing simple yes/no or true/false responses, checkboxes, or binary options. These fields are straightforward and efficient for storing data that requires a binary decision, such as whether a task is completed, a condition is met, or an option is selected.
The format to enter the default value is boolean, representing two possible states, for example “true” or “false”.
Dropdown:
This custom field, also known as a dropdown list, is a user interface element that presents a list of predefined options for users to select from. This type of custom field allows users to choose a single option from a list of available choices presented in a dropdown menu. These options can represent various categories, statuses, choices, or attributes relevant to the data being captured, e.g., company size (small, medium, large), country selection (list of countries).
When creating a dropdown custom field, users would first need to define the set or list of options that correctly identify the possible answers to the field established and that will be displayed in the dropdown menu.
Secondly, it is necessary to upload a CSV file with this set of options by clicking “add values”. There is a downloaded example in CSV format.
For example, for a dropdown custom field named “company size”, users would have to upload:
```
ID,Name (EN_GB),Name (ES_ES),Name (CA_ES),Name (ES_MX),
Defaultoption-001,en_GB,es_ES,ca_ES,es_MX,1
small,small,pequeña,petita,pequeña,1
medium,medium,mediana,mitjana,mediana,
large,large,grande,gran,grande,
```In this example, it is important to notice that users need to format the text according to each language they previously defined and enabled. It is recommended to not leave any language column blank, to fulfill each language column as you have enabled. If you leave a language with no information (blank), there will be an empty value in “dropdown values”.
If a user needs to update the values of an existing dropdown custom field, there is an “update values” option, where users need to upload a new CSV file with the new set of options, following the same format logic as before explained.
When editing dropdown custom field, it is important to notice that only adding options, changing the labels and changing the default option are allowed.
To remove or change values is not allowed in the backoffice because this could generate inconsistencies or errors in the previous information collected.
Money:
A custom field money is a data field specifically designed to store and manage monetary values. This type of custom field is optimized for handling financial data, such as currency amounts, prices, costs, budgets, or transaction values.
Custom field money includes features such as:
- Currency Symbol: The ability to specify the currency symbol or code associated with the monetary value (e.g., $ for US dollars, € for euros).
You can get the allowed currencies using this API endpoint .
In the backoffice by default, you can find these currencies: USD, EUR, GBP, JPY, MXN, PEN.
- Formatting: Support for formatting options such as thousands separators, decimal separators, and currency placement to enhance readability and consistency.
In the backoffice a user should enter the money value with a comma and two decimals. For example, 4,50 USD.
The format to enter the default value is a JSON, according to object (amount: integer, currency: string). For example:
{
"amount": "1",
"currency": "EUR"
}
Image:
A custom field image is a data field that allows users to upload, store, and display images or graphics associated with a particular record or entity. This type of custom field enables users to include visual content such as photographs, logos, icons, diagrams, or other graphical elements alongside textual or numerical data. This custom field enables you to attach images in this supported formats: PNG, JPEG, GIF.
To upload images, the user should use the API endpoint, and put the file url here, in the “url” field. In case the custom field allows multiple files (it is set in the custom field), you should do the same process for each file keeping the same custom field reference (reference field).
Also, we allow external images. In this case, you must put the external image url in the “url” field and the id field goes empty. We don’t allow both id and url fields are empty.
The format to enter the default value is a JSON, according to object (url(optional): string, id(optional): string). For example,
{
"id": "img_0123ADR13S5KWSO110"
}
{
"url": "https://external-url-example.app/path/to/image.jpg"
}
File:
A custom field file is a data field that allows users to upload, store, and manage files or documents associated with a particular record or entity. This custom field enables users to attach files in this supported format:
- Acrobat (.pdf)
- Excel (.xls, xlsx)
- Open Office (.odt)
- Word (.doc, .docx)
- Rich Text Format (.rtf)
- Plain text (.txt)
- Comma-separated values (.csv)
The user should use the API endpoint to upload files, and put the id here, in the “id” field. In case the custom field allows multiple files (it is set in the custom field), you should do the same process for each file keeping the same custom field reference (reference field).
Also, we allow external files. In this case, you must put the external file url in the “url” field and the id field goes empty.
We don’t allow both id and url fields to be empty.
The format to enter the default value is a JSON, according to Object (id (optional): string, name: string, url(optional): string). For example,
{
"id": "file_01FPHJA12AZSH133SAS11K",
"name": "my file"
}
{
"url": "https://external-url-example.app/path/to/file.pdf",
"name": "my file"
}
Editing Custom Fields
Editing custom fields can be restricted to the bare minimum, and if important changes are required, clients are advised to delete and create custom fields again.
The user who can edit a custom field, by default, is an “owner” user, but it will depend on which user has enabled this kind of permission.
The fields that can be editable are:
- custom field name, default value and required field
The fields that can’t be editable are:
- ID, field scope and field type
Deleting Custom Fields
Deleting a field can be restricted on some occasions, depending on the roles and permissions configured.
There is a possibility to erase all custom fields created, but this will only be permitted to “owner” users or users who have this kind of permission enabled.
A company admin user, for example, cannot delete or edit a custom field; they can only see them.
