Recurring Deals: Overview of Methods

A recurring deal is created automatically from a template with a defined period and number of repetitions. The template retains the field values of future deals, and the repetition settings define how often and until when new deals are created in the selected Sales Funnel.

Quick navigation: all methods and events

User documentation: Recurring deals

Identifiers of a Recurring Deal TemplateIdentifiers of a Recurring Deal Template

A template consists of two objects: the template deal, which retains the field values, and the record with the repetition settings. They have different identifiers and are not interchangeable in the methods.

Identifier	What It Denotes	Where It Is Used
ID	Identifier of the repetition settings	The id parameter of the methods crm.deal.recurring.get, crm.deal.recurring.update, crm.deal.recurring.delete, and crm.deal.recurring.expose
DEAL_ID	Identifier of the template deal from which the field values are copied	The id parameter of the deal methods — crm.deal.get, crm.deal.update
BASED_ID	Identifier of the source deal the template was made from	The id parameter of the method crm.deal.get

The method crm.deal.recurring.add handles a regular deal and a template deal differently.

• If you pass a regular deal in DEAL_ID, Bitrix24 creates a copy of it, and that copy becomes the template deal. In the repetition settings, DEAL_ID points to this copy, and BASED_ID points to the source deal. Product items are copied into the template along with the fields
• If you pass a deal that is already marked as a template in DEAL_ID, the repetition settings are linked to it directly, and BASED_ID remains empty. Settings cannot be added to the same deal twice — the method returns the error Deal already have had recurring settings

Both identifiers can be retrieved using the method crm.deal.recurring.list.

Getting StartedGetting Started

1. Create a deal using the method crm.deal.add or take an existing one — its fields become the basis of the template
2. Find out the identifier of the funnel in which the deals are to be created using the method crm.category.list with the parameter entityTypeId = 2
3. Create the template using the method crm.deal.recurring.add: pass DEAL_ID, the funnel in CATEGORY_ID, the date of the first run in START_DATE, and the frequency in PARAMS
4. Limit the number of repetitions with the fields IS_LIMIT, LIMIT_REPEAT, and LIMIT_DATE if the deals are not meant to be created indefinitely
5. Check the result using the method crm.deal.recurring.get — it returns the date of the next run NEXT_EXECUTION and the counter of created deals COUNTER_REPEAT
6. Create a deal from the template outside the schedule using the method crm.deal.recurring.expose
7. Subscribe to the recurring deal events to receive notifications in your application

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

Deals. The field values of future deals are retained by the template deal. To view or change them, take DEAL_ID from the result of the method crm.deal.recurring.list and pass it to the id parameter of the methods crm.deal.get and crm.deal.update. Every deal created from a template is a regular deal, so it triggers the event onCrmDealAdd along with the event onCrmDealRecurringExpose.

Funnels. Sales funnels are managed by the group of methods crm.category.* with entityTypeId = 2. To have deals created from the template in the required funnel, pass its identifier in the CATEGORY_ID field. You can retrieve the list of funnels using the method crm.category.list.

Products. The product items of the template deal are copied into every new deal. You can change them with the group of methods crm.item.productrow.*: pass ownerType = D and the DEAL_ID value from the result of the method crm.deal.recurring.list in the ownerId parameter.

Clients. The company and contacts of the template deal are also carried over to new deals. The company is changed by the method crm.deal.update through the COMPANY_ID field, and the contacts by the group of methods crm.deal.contact.*. Take the identifier of the template deal from the DEAL_ID field of the method crm.deal.recurring.list.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can execute the method: depending on the method — all methods check the access permissions for deals. Reading the settings requires the "read" access permission for deals, creating a template requires the "add" and "modify" permissions, and deleting one requires the "delete" permission