Deals in CRM: Overview of Methods

A deal is one of the key objects in CRM, where you can:

• manage the sales process of a product or service, including tracking stages and accepting online payments
• engage in dialogue with the client: calls, e-mails, chats in open channels
• view the history of interactions: activities, timeline records

Quick navigation: all methods and events

User documentation: deals in Bitrix24

Connection of Deals with Other CRM ObjectsConnection of Deals with Other CRM Objects

Client. A field in the deal card that consists of the associated company and contacts. All activities related to calls, e-mails, and chats with the contact or company will be saved in the active deal card. There can be only one company in the field, and it is accessed directly through the deal field COMPANY_ID. Multiple contacts can be specified, and interaction with them is conducted through a separate group of methods crm.deal.contact.*.

Products. Adding, modifying, and deleting product items in deals can be done through the group of methods crm.item.productrow.*.

Payments. Adding, modifying, and deleting payment documents in deals can be done through the group of methods crm.item.payment.*.

Sales Funnels and Deal StagesSales Funnels and Deal Stages

You can create various sales funnels for deals and manage them through the group of methods crm.category.* where entityTypeId of the deal = 2.

Each funnel will have its own stages. These can be managed through the group of CRM reference methods — crm.status.*. The ENTITY_ID of deal statuses is unique for each direction — DEAL_STAGE_xx.

You can retrieve the history of a deal's movement through stages using the method crm.stagehistory.list.

How to Change a Deal's FunnelHow to Change a Deal's Funnel

The method crm.deal.update can only change the stage of a deal within the current funnel. If you pass a STAGE_ID that does not belong to the current funnel, nothing will change.

To move a deal to a stage in another funnel, use the method crm.item.update with the following parameters:

• entityTypeId — 2 for the deal,
• id — the id of the deal you are moving,
• categoryId — the id of the funnel to which you are moving the deal. This can be obtained using the method crm.category.list
• stageId — the id of the stage in the new funnel. This can be obtained using the method crm.status.list

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.update
        

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"entityTypeId":2,"id":233,"fields":{"STAGE_ID":"EXECUTING","categoryId":0},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.item.update
        

try
        {
            const response = await $b24.callMethod(
                'crm.item.update',
                {
                    entityTypeId: 2,
                    id: 233,
                    fields: {
                        STAGE_ID: 'EXECUTING',
                        categoryId: 0
                    }
                }
            );
            
            const result = response.getData().result;
            console.log('Updated item with ID:', result);
            
            processResult(result);
        }
        catch( error )
        {
            console.error('Error:', error);
        }
        

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.item.update',
                    [
                        'entityTypeId' => 2,
                        'id' => 233,
                        'fields' => [
                            'STAGE_ID' => 'EXECUTING',
                            'categoryId' => 0
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
            processData($result);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error updating item: ' . $e->getMessage();
        }
        

BX24.callMethod(
            "crm.item.update",
            {
                entityTypeId: 2,
                id: 233,
                fields:
                {
                    "STAGE_ID": "EXECUTING",
                    "categoryId": 0
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data());
            }
        );
        

require_once('crest.php');
        
        $result = CRest::call(
            'crm.item.update',
            [
                'entityTypeId' => 2,
                'id' => 233,
                'fields' => [
                    'STAGE_ID' => 'EXECUTING',
                    'categoryId' => 0
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Deal CardDeal Card

The main workspace in a deal is the General tab of its card. It consists of two parts:

• the left part, which contains fields with information. If the system fields are insufficient, you can create your own custom fields. They allow you to store information in various data formats: string, number, link, address, and others. To create, modify, retrieve, or delete custom deal fields, the group of methods crm.deal.userfield.* is used.

• the right part, which contains the deal's timeline. In it, you can create, edit, filter, and delete CRM activities — the group of methods crm.activity.*, and timeline records — the group of methods crm.timeline.*.

The parameters of the deal card can be managed depending on the funnel through the group of methods crm.deal.details.configuration.*.

WidgetsWidgets

You can embed an application into the deal card. By embedding, you can use the application without leaving the deal card.

There are two embedding scenarios:

• Use special embedding locations. For example, by creating your own tab.
• Create a custom field, into which the interface of your application will be loaded.

Recurring DealsRecurring Deals

Automatic creation of similar recurring deals based on templates. To manage templates, the group of methods crm.deal.recurring.* is used.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can execute the method: depending on the method

MainMain

Recurring DealsRecurring Deals

Custom FieldsCustom Fields

Deal ContactsDeal Contacts

Managing Deal CardsManaging Deal Cards