# Recurring deals

Recurring settings describe automatic deal creation, for example a monthly subscription. The recurring settings ID differs from the template deal ID. Availability depends on your Bitrix24 plan.

Bitrix24 API: `crm.deal.recurring.*`

Scope: `crm`

## Operations

- [List recurring deals](./recurring-deals/list.md) — `GET /v1/recurring-deals`
- [Get recurring settings](./recurring-deals/get.md) — `GET /v1/recurring-deals/:id`
- [Create recurring settings](./recurring-deals/create.md) — `POST /v1/recurring-deals`
- [Update recurring settings](./recurring-deals/update.md) — `PATCH /v1/recurring-deals/:id`
- [Delete recurring settings](./recurring-deals/delete.md) — `DELETE /v1/recurring-deals/:id`
- [Recurring deal fields](./recurring-deals/fields.md) — `GET /v1/recurring-deals/fields`
- [Search recurring deals](./recurring-deals/search.md) — `POST /v1/recurring-deals/search`
- [Batch operations](./recurring-deals/batch.md) — `POST /v1/recurring-deals/batch`
- [Aggregate](./recurring-deals/aggregate.md) — `POST /v1/recurring-deals/aggregate`
- [Create a deal from a template](./recurring-deals/expose.md) — `POST /v1/recurring-deals/:id/expose`

## Fields

| Field | Type | Description |
|---|---|---|
| `id` | number | Recurring settings ID. Read only. |
| `dealId` | number | Template deal ID; ordinary source deals are copied on creation.  |
| `basedId` | number | Source deal ID. Read only. |
| `active` | boolean | Whether automatic repetition is active.  |
| `nextExecution` | datetime | Next execution date. Read only. |
| `lastExecution` | datetime | Last execution date. Read only. |
| `counterRepeat` | number | Executed repetitions. Read only. |
| `startDate` | date | Schedule start date.  |
| `categoryId` | number | Pipeline for newly generated deals.  |
| `isLimit` | string | Repetition limit mode.  |
| `limitRepeat` | number | Maximum repetition count for T.  |
| `limitDate` | date | Last allowed date for D.  |
| `params` | object | Complete schedule parameters; replace as a whole on update.  |

## Schedule parameters

`params` uses camelCase keys. Units are `day`, `week`, `month`, `year`; Bitrix24 also accepts native numeric unit codes. Positive intervals are numbers or numeric strings. The platform normalizes its defaults; use the returned settings when checking a schedule.

| Parameter | Type | Meaning |
|---|---|---|
| `mode` | string | single or multiple |
| `singleBeforeStartDateValue` | number | Offset before start date |
| `singleBeforeStartDateType` | string | Offset unit: day, week, month or year |
| `multipleType` | string | Repeat unit: day, week, month or year |
| `multipleInterval` | number | Interval in repeat units |
| `offsetBeginDateType` | string | Generated deal start-date offset unit |
| `offsetBeginDateValue` | number | Generated deal start-date offset |
| `offsetCloseDateType` | string | Generated deal close-date offset unit |
| `offsetCloseDateValue` | number | Generated deal close-date offset |

## Key fields

`id` identifies the recurring settings. `dealId` points to a [deal template](./deals/get.md), `basedId` to the original deal. `active` controls automatic repetition; `isLimit` controls its limit.

## Before you start

A standard source deal is copied into a separate template. Store the returned IDs for cleanup. `params` is replaced as a complete schedule. Manual expose can create a deal while automatic repetition is disabled.

## Typical scenario

Create a [deal](./deals/create.md), add recurring settings, store the returned template ID, and expose the template when needed. Deleting settings while the template exists returns 422. Deleting an owned template through deals removes its settings automatically; delete the source and generated deals separately.

## Limits

The feature depends on the Bitrix24 plan and the caller's CRM permissions. Generic lists use standard pagination; schedule objects are not filterable or sortable. Repeating expose can create another deal.