How to Configure Rounding for a Custom Field of Type "Number"
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
Custom fields have standard settings: name, required status, and multiple values.
Additionally, there are specialized settings depending on the field type:
- values for lists
- rounding precision for numbers
- currency for monetary fields
To obtain specialized settings for the "Number" type — double, we use the method crm.userfield.settings.fields:
BX24.callMethod(
"crm.userfield.settings.fields",
{
type: "double" // type of the custom field
},
function(result)
{
if(result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'crm.userfield.settings.fields',
[
'type' => 'double' // Type of the custom field
]
);
if (isset($result['error'])) {
echo 'Error: ' . $result['error_description'];
} else {
echo '<PRE>';
print_r($result['result']);
echo '</PRE>';
}
As a result, we will receive two settings: default value and precision.
{
"result": {
"DEFAULT_VALUE": {
"type": "double",
"title": "Default Value"
},
"PRECISION": {
"type": "int",
"title": "Precision"
}
}
}
Creating a Numeric Field with Rounding Configuration
We will create a field of type number with a precision setting of three decimal places. If a value with four or more decimal places is entered in the field, it will automatically round to three decimal places.
To create a custom field, we use the method userfieldconfig.add with the following parameters:
-
moduleId— the identifier of the module in which the method will create the field, a required parameter. In this example, we create a field for deals, the module iscrm. -
field[entityId]— the identifier of the object in the formatCRM_ + {ID}, a required parameter. The list of identifiers for objects can be found in the article — Entity ID Identifiers. In this example, we will specifyCRM_DEAL. -
field[fieldName]— the field code in the formatUF_ + {object identifier} + _ + {arbitrary string in UPPERCASE}. The length limit for the code is 50 characters, a required parameter. In this example, we will specifyUF_CRM_DEAL_NEW_DOUBLE_FIELD. -
field[userTypeId]— the identifier of the field type, a required parameter. In this example, we will specifydoubleto create a number type field. -
field[editFormLabel]— an array of names for displaying the field in Bitrix24 in different languages. An optional parameter; if no name is provided, the field code will be displayed in Bitrix24. -
field[settings]— an array of additional settings for the field depending on its type. An optional parameter; if not provided, default settings will be used. In this example, we will specify thePRECISIONsetting — precision. We will pass an integer equal to the number of decimal places.
BX24.callMethod(
'userfieldconfig.add',
{
moduleId: 'crm', // Module identifier
field: {
entityId: 'CRM_DEAL', // Object identifier
fieldName: 'UF_CRM_DEAL_NEW_DOUBLE_FIELD', // Field code
userTypeId: 'double', // Field type identifier
editFormLabel: {
'en': 'Number with Rounding', // Field name in English
'en': 'PRECISION double' // Field name in English
},
settings: { // Additional field settings
PRECISION: 3, // Number of decimal places
},
}
},
);
require_once('crest.php');
$result = CRest::call(
'userfieldconfig.add',
[
'moduleId' => 'crm', // Module identifier
'field' => [
'entityId' => 'CRM_DEAL', // Object identifier
'fieldName' => 'UF_CRM_DEAL_NEW_DOUBLE_FIELD', // Field code
'userTypeId' => 'double', // Field type identifier
'editFormLabel' => [
'en' => 'Number with Rounding', // Field name in English
'en' => 'PRECISION double' // Field name in English
],
'settings' => [ // Additional field settings
'PRECISION' => 3 // Number of decimal places
]
]
]
);
As a result, we will receive the data of the created field.
{
"result": {
"field": {
"id": "6961",
"entityId": "CRM_DEAL",
"fieldName": "UF_CRM_DEAL_NEW_DOUBLE_FIELD",
"userTypeId": "double",
"xmlId": null,
"sort": "100",
"multiple": "N",
"mandatory": "N",
"showFilter": "N",
"showInList": "Y",
"editInList": "Y",
"isSearchable": "N",
"settings": {
"PRECISION": 3,
"SIZE": 20,
"MIN_VALUE": 0,
"MAX_VALUE": 0,
"DEFAULT_VALUE": null
},
"languageId": {
"en": "en"
},
"editFormLabel": {
"en": "PRECISION double",
"en": "Number with Rounding"
},
"listColumnLabel": {
"en": null
},
"listFilterLabel": {
"en": null
},
"errorMessage": {
"en": null
},
"helpMessage": {
"en": null
}
}
},
}
Modifying the Setting of an Existing Numeric Field
To change the rounding setting of an existing field, we use the method userfieldconfig.update specifying the field ID. The field ID can be obtained in two ways: when creating the field using the method userfieldconfig.add or through the method for retrieving the list of custom fields of the object. In this example, we are dealing with a deal field, so we will use the method crm.deal.userfield.list.
1. Retrieving the Field ID
To get the field ID, we use the method crm.deal.userfield.list with the following parameters:
-
filter[LANG]— a filter by language used to display field names in the desired language. Without this filter, names will not be displayed. -
filter[USER_TYPE_ID]— a filter by field type used to retrieve only fields of type "Number" in the result.
BX24.callMethod(
"crm.deal.userfield.list",
{
filter: {
LANG: 'en', // Language filter for displaying field names
USER_TYPE_ID: 'double' // Field type filter
}
}
);
require_once('crest.php');
$result = CRest::call(
'crm.deal.userfield.list',
[
'filter' => [
'LANG' => 'en', // Language filter for displaying field names
'USER_TYPE_ID' => 'double' // Field type filter
]
]
);
As a result, we will receive all numeric fields of deals with their names.
{
"result": [
{
"ID": "6963",
"ENTITY_ID": "CRM_DEAL",
"FIELD_NAME": "UF_CRM_1740471712",
"USER_TYPE_ID": "double",
"XML_ID": null,
"SORT": "100",
"MULTIPLE": "N",
"MANDATORY": "N",
"SHOW_FILTER": "E",
"SHOW_IN_LIST": "Y",
"EDIT_IN_LIST": "Y",
"IS_SEARCHABLE": "N",
"SETTINGS": {
"PRECISION": 2,
"SIZE": 20,
"MIN_VALUE": 0,
"MAX_VALUE": 0,
"DEFAULT_VALUE": null
},
"EDIT_FORM_LABEL": "Advance",
"LIST_COLUMN_LABEL": "Advance",
"LIST_FILTER_LABEL": "Advance",
"ERROR_MESSAGE": null,
"HELP_MESSAGE": null
},
{
"ID": "6807",
"ENTITY_ID": "CRM_DEAL",
"FIELD_NAME": "UF_CRM_1723464314",
"USER_TYPE_ID": "double",
"XML_ID": null,
"SORT": "150",
"MULTIPLE": "N",
"MANDATORY": "N",
"SHOW_FILTER": "E",
"SHOW_IN_LIST": "Y",
"EDIT_IN_LIST": "Y",
"IS_SEARCHABLE": "N",
"SETTINGS": {
"PRECISION": 2,
"SIZE": 20,
"MIN_VALUE": 0,
"MAX_VALUE": 0,
"DEFAULT_VALUE": null
},
"EDIT_FORM_LABEL": "Refund Amount",
"LIST_COLUMN_LABEL": "Refund Amount",
"LIST_FILTER_LABEL": "Refund Amount",
"ERROR_MESSAGE": null,
"HELP_MESSAGE": null
}
],
"total": 2,
}
2. Modifying the Rounding Setting for the Field Value
To change the setting of an existing field, we use the method userfieldconfig.update with the following parameters:
-
moduleId— the identifier of the module in which the method will modify the field, a required parameter. In this example, we are modifying a deal field, the module iscrm. -
id— the identifier of the custom field, a required parameter. In this example, we will pass the field ID obtained from the method crm.deal.userfield.list. -
field[settings]— an array of additional settings for the field depending on its type. In this example, we will specify thePRECISIONsetting — precision. We will pass an integer equal to the number of decimal places.
BX24.callMethod(
'userfieldconfig.update',
{
moduleId: 'crm', // Module identifier
id: 6807, // ID of the custom field
field: {
settings: { // Additional field settings
PRECISION: 3, // Number of decimal places
},
}
},
);
require_once('crest.php');
$result = CRest::call(
'userfieldconfig.update',
[
'moduleId' => 'crm', // Module identifier
'id' => 6807, // ID of the custom field
'field' => [
'settings' => [ // Additional field settings
'PRECISION' => 3 // Number of decimal places
]
]
]
);
As a result, we will receive the data of the modified field.
{
"result": {
"field": {
"id": "6807",
"entityId": "CRM_DEAL",
"fieldName": "UF_CRM_1723464314",
"userTypeId": "double",
"xmlId": null,
"sort": "150",
"multiple": "N",
"mandatory": "N",
"showFilter": "E",
"showInList": "Y",
"editInList": "Y",
"isSearchable": "N",
"settings": {
"PRECISION": 3,
"SIZE": 20,
"MIN_VALUE": 0,
"MAX_VALUE": 0,
"DEFAULT_VALUE": null
},
"languageId": {
"en": "en"
},
"editFormLabel": {
"en": "Refund Amount"
},
"listColumnLabel": {
"en": "Refund Amount"
},
"listFilterLabel": {
"en": "Refund Amount"
},
"errorMessage": {
"en": null
},
"helpMessage": {
"en": null
}
}
},
}
Code Example
// Function to find and update a custom field
function updateUserField() {
// Prompt the user for the field name
var fieldName = prompt("Enter the field name:");
// First method: Retrieve the list of all custom fields of type 'double'
BX24.callMethod(
"crm.deal.userfield.list",
{
filter: {
LANG: 'en', // Language filter for displaying field names
USER_TYPE_ID: 'double' // Field type filter
}
},
function(result) {
if (result.error()) {
console.error(result.error());
} else {
// Iterate through the retrieved fields to find the desired one by name
var fields = result.data();
var fieldId = null;
for (var i = 0; i < fields.length; i++) {
if (fields[i].EDIT_FORM_LABEL === fieldName) {
fieldId = fields[i].ID;
break;
}
}
if (fieldId) {
// Second method: Update the settings of the found field
BX24.callMethod(
'userfieldconfig.update',
{
moduleId: 'crm', // Module identifier
id: fieldId, // ID of the found custom field
field: {
settings: {
PRECISION: 3 // Number of decimal places
}
}
},
function(updateResult) {
if (updateResult.error()) {
console.error(updateResult.error());
} else {
console.log("Field settings successfully updated.");
}
}
);
} else {
console.log("Field with the specified name not found.");
}
}
}
);
}
// Run the function
updateUserField();
require_once('crest.php');
// Function to find and update a custom field
function updateUserField($fieldName) {
// First method: Retrieve the list of all custom fields of type 'double'
$result = CRest::call(
'crm.deal.userfield.list',
[
'filter' => [
'LANG' => 'en', // Language filter for displaying field names
'USER_TYPE_ID' => 'double' // Field type filter
]
]
);
if (isset($result['error'])) {
echo 'Error: ' . $result['error_description'];
} else {
// Iterate through the retrieved fields to find the desired one by name
$fields = $result['result'];
$fieldId = null;
foreach ($fields as $field) {
if ($field['EDIT_FORM_LABEL'] === $fieldName) {
$fieldId = $field['ID'];
break;
}
}
if ($fieldId) {
// Second method: Update the settings of the found field
$updateResult = CRest::call(
'userfieldconfig.update',
[
'moduleId' => 'crm', // Module identifier
'id' => $fieldId, // ID of the found custom field
'field' => [
'settings' => [
'PRECISION' => 3 // Number of decimal places
]
]
]
);
if (isset($updateResult['error'])) {
echo 'Error: ' . $updateResult['error_description'];
} else {
echo 'Field settings successfully updated.';
}
} else {
echo 'Field with the specified name not found.';
}
}
}
// Prompt the user for the field name
$fieldName = readline("Enter the field name: ");
// Run the function
updateUserField($fieldName);