[{"data":1,"prerenderedAt":17},["ShallowReactive",2],{"docs-entities\u002Frecurring-deals":3,"docs-tabs-entities\u002Frecurring-deals":6},{"content":4,"lastmod":5},"# Recurring deals\n\nRecurring 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.\n\nBitrix24 API: `crm.deal.recurring.*`\n\nScope: `crm`\n\n## Operations\n\n- [List recurring deals](.\u002Frecurring-deals\u002Flist.md) — `GET \u002Fv1\u002Frecurring-deals`\n- [Get recurring settings](.\u002Frecurring-deals\u002Fget.md) — `GET \u002Fv1\u002Frecurring-deals\u002F:id`\n- [Create recurring settings](.\u002Frecurring-deals\u002Fcreate.md) — `POST \u002Fv1\u002Frecurring-deals`\n- [Update recurring settings](.\u002Frecurring-deals\u002Fupdate.md) — `PATCH \u002Fv1\u002Frecurring-deals\u002F:id`\n- [Delete recurring settings](.\u002Frecurring-deals\u002Fdelete.md) — `DELETE \u002Fv1\u002Frecurring-deals\u002F:id`\n- [Recurring deal fields](.\u002Frecurring-deals\u002Ffields.md) — `GET \u002Fv1\u002Frecurring-deals\u002Ffields`\n- [Search recurring deals](.\u002Frecurring-deals\u002Fsearch.md) — `POST \u002Fv1\u002Frecurring-deals\u002Fsearch`\n- [Batch operations](.\u002Frecurring-deals\u002Fbatch.md) — `POST \u002Fv1\u002Frecurring-deals\u002Fbatch`\n- [Aggregate](.\u002Frecurring-deals\u002Faggregate.md) — `POST \u002Fv1\u002Frecurring-deals\u002Faggregate`\n- [Create a deal from a template](.\u002Frecurring-deals\u002Fexpose.md) — `POST \u002Fv1\u002Frecurring-deals\u002F:id\u002Fexpose`\n\n## Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | number | Recurring settings ID. Read only. |\n| `dealId` | number | Template deal ID; ordinary source deals are copied on creation.  |\n| `basedId` | number | Source deal ID. Read only. |\n| `active` | boolean | Whether automatic repetition is active.  |\n| `nextExecution` | datetime | Next execution date. Read only. |\n| `lastExecution` | datetime | Last execution date. Read only. |\n| `counterRepeat` | number | Executed repetitions. Read only. |\n| `startDate` | date | Schedule start date.  |\n| `categoryId` | number | Pipeline for newly generated deals.  |\n| `isLimit` | string | Repetition limit mode.  |\n| `limitRepeat` | number | Maximum repetition count for T.  |\n| `limitDate` | date | Last allowed date for D.  |\n| `params` | object | Complete schedule parameters; replace as a whole on update.  |\n\n## Schedule parameters\n\n`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.\n\n| Parameter | Type | Meaning |\n|---|---|---|\n| `mode` | string | single or multiple |\n| `singleBeforeStartDateValue` | number | Offset before start date |\n| `singleBeforeStartDateType` | string | Offset unit: day, week, month or year |\n| `multipleType` | string | Repeat unit: day, week, month or year |\n| `multipleInterval` | number | Interval in repeat units |\n| `offsetBeginDateType` | string | Generated deal start-date offset unit |\n| `offsetBeginDateValue` | number | Generated deal start-date offset |\n| `offsetCloseDateType` | string | Generated deal close-date offset unit |\n| `offsetCloseDateValue` | number | Generated deal close-date offset |\n\n## Key fields\n\n`id` identifies the recurring settings. `dealId` points to a [deal template](.\u002Fdeals\u002Fget.md), `basedId` to the original deal. `active` controls automatic repetition; `isLimit` controls its limit.\n\n## Before you start\n\nA 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.\n\n## Typical scenario\n\nCreate a [deal](.\u002Fdeals\u002Fcreate.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.\n\n## Limits\n\nThe 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.\n\n## See also\n\n- [Deals](\u002Fdocs\u002Fentities\u002Fdeals)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n","2026-10-13",{"recurring-deals\u002Flist.md":7,"recurring-deals\u002Fget.md":8,"recurring-deals\u002Fcreate.md":9,"recurring-deals\u002Fupdate.md":10,"recurring-deals\u002Fdelete.md":11,"recurring-deals\u002Ffields.md":12,"recurring-deals\u002Fsearch.md":13,"recurring-deals\u002Fbatch.md":14,"recurring-deals\u002Faggregate.md":15,"recurring-deals\u002Fexpose.md":16},"## List recurring deals\n\n`GET \u002Fv1\u002Frecurring-deals`\n\nReturns deal recurrence settings with filtering, sorting and field selection. Use it to review schedules and their activity.\n\n## Parameters\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `filter` | object | No | Filter by fields from [Recurring deal fields](.\u002Ffields.md).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example: `?filter[active]=false`, or a JSON string |\n| `sort` | string \u002F object \u002F string[] | No | Sort fields. `id` sorts ascending, `-id` descending |\n| `order` | object | No | Alternative to `sort`, for example `{\"id\":\"desc\"}` |\n| `select` | string \u002F string[] | No | Response fields. A comma-separated string or an array of names |\n| `limit` | number | No | Selection size, default 50, maximum 5000 |\n| `offset` | number | No | Offset from the start of the selection |\n| `withTotal` | boolean | No | Requests the total count. With `false`, `meta.total` is still returned |\n\n**Pagination.** The server reads multiple pages for `limit > 50`, up to 5000 records per request. Use `offset` and `meta.hasMore` to continue reading.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object[] | Recurrence settings. See [recurring deal fields](.\u002Ffields.md) |\n| `meta.total` | number | Total matching settings, when returned |\n| `meta.hasMore` | boolean | Whether more records are available |\n| `meta.warnings` | object[] | Warnings, when returned. Unknown `select` fields can be ignored in a successful request |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 17,\n      \"active\": false\n    },\n    {\n      \"id\": 9,\n      \"active\": false\n    }\n  ],\n  \"meta\": {\n    \"total\": 4,\n    \"hasMore\": true\n  }\n}\n```\n\n## Error response example\n\n400 — unknown filter field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'unknownField' for entity 'recurring-deals'. Available: id, dealId, basedId, active, nextExecution, lastExecution, counterRepeat, startDate, categoryId, isLimit, limitRepeat, limitDate\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `UNKNOWN_FILTER_FIELD` | The filter references an unknown field. See the error message and [field definitions](.\u002Ffields.md) |\n| 400 | `INVALID_FILTER_FIELD` | A field name starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition using `$or` or `$and` |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions map to the same filter condition. Supply only one |\n| 400 | `INVALID_SORT_FIELD` | Sorting uses a forbidden name: `__proto__`, `constructor` or `prototype` |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting references an unknown field |\n| 400 | `INVALID_SORT_DIRECTION` | A sort direction is not one of the strings `asc`, `desc`, `ASC`, `DESC` or the numbers `1`, `-1` |\n| 400 | `INVALID_FILTER` | `filter` is not an object or a JSON string containing an object, or two filter formats are mixed |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` |\n| 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nThe response can include settings with `active: false`. To retrieve active schedules only, filter by `active: true`.\n\n## See also\n\n- [Get a recurring deal](.\u002Fget.md)\n- [Recurring deal fields](.\u002Ffields.md)\n- [Search recurring deals](.\u002Fsearch.md)\n- [Aggregate recurring deals](.\u002Faggregate.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n","## Get recurring settings\n\n`GET \u002Fv1\u002Frecurring-deals\u002F:id`\n\nReturns a deal recurrence setting by its ID. Use it to read the schedule, repetition limits and execution history.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `id` | number | Yes | Setting ID in the request path. A non-negative safe integer. Get IDs from [the recurring deal list](.\u002Flist.md) |\n| `select` | string \u002F string[] | No | Select response fields, for example `select=id,active` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F1\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F1\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F1', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F1', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object | Recurrence setting. See [recurring deal fields](.\u002Ffields.md) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 1,\n    \"dealId\": 575,\n    \"basedId\": 573,\n    \"active\": false,\n    \"categoryId\": 1,\n    \"isLimit\": \"T\",\n    \"counterRepeat\": 2,\n    \"limitRepeat\": 2,\n    \"limitDate\": null,\n    \"startDate\": \"2020-06-15\",\n    \"nextExecution\": null,\n    \"lastExecution\": \"2020-06-16T22:00:00.000Z\",\n    \"params\": {\n      \"mode\": \"multiple\",\n      \"singleBeforeStartDateValue\": 0,\n      \"singleBeforeStartDateType\": \"day\",\n      \"multipleType\": \"day\",\n      \"multipleInterval\": 1,\n      \"offsetBeginDateType\": \"day\",\n      \"offsetBeginDateValue\": 1,\n      \"offsetCloseDateType\": \"day\",\n      \"offsetCloseDateValue\": 1\n    }\n  }\n}\n```\n\n## Error response example\n\n404 — setting not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Recurring deal is not found.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_PARAMS` | `id` is not a non-negative safe integer |\n| 404 | `ENTITY_NOT_FOUND` | The setting was not found. Bitrix24 message: `Recurring deal is not found.` |\n| 404 | `ENTITY_NOT_FOUND` | The Bitrix24 call succeeded but returned no object. Message: `recurringDeal \u003Cid> not found` |\n| 422 | `BITRIX_ERROR` | For `id=0`, Bitrix24 returns `ID is not defined or invalid.` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` |\n| 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List recurring deals](.\u002Flist.md)\n- [Recurring deal fields](.\u002Ffields.md)\n- [Search recurring deals](.\u002Fsearch.md)\n- [Aggregate recurring deals](.\u002Faggregate.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n","## Create recurring settings\n\n`POST \u002Fv1\u002Frecurring-deals`\n\nCreates settings for automatic deal repetition.\n\n## Request fields (body)\n\nPass the fields at the JSON root.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `dealId` | number \u002F string | Yes | Source deal ID, a positive integer. A numeric string is also accepted. Get IDs from [List deals](\u002Fdocs\u002Fentities\u002Fdeals\u002Flist) |\n| `active` | boolean \u002F string \u002F null | No | Whether automatic repetition is active. String forms: `\"true\"` \u002F `\"false\"`, `\"yes\"` \u002F `\"no\"`, `\"y\"` \u002F `\"n\"`, `\"1\"` \u002F `\"0\"` |\n| `startDate` | date \u002F null | No | Schedule start date, for example `2027-01-01` |\n| `categoryId` | number \u002F string \u002F null | No | Funnel ID for the generated deals. A numeric string is also accepted. Get IDs from [List pipelines](\u002Fdocs\u002Fentities\u002Fdeal-categories\u002Flist) |\n| `isLimit` | string | No | Repetition limit: `N` — unlimited, `T` — by the `limitRepeat` count, `D` — by the `limitDate` date |\n| `limitRepeat` | number \u002F string \u002F null | No | Integer repetition count for mode `T`. A numeric string is also accepted |\n| `limitDate` | date \u002F null | No | Last allowed date for mode `D` |\n| `params` | object | No | Complete schedule object. The parameters are listed below |\n| `params.mode` | string \u002F number \u002F null | No | Mode: `single` or `multiple`. Numeric codes `1` and `2` are also accepted |\n| `params.singleBeforeStartDateValue` | number \u002F string \u002F null | No | Non-negative integer offset before the start date. A numeric string is also accepted |\n| `params.singleBeforeStartDateType` | string \u002F number \u002F null | No | Offset unit: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.multipleType` | string \u002F number \u002F null | No | Repetition unit: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.multipleInterval` | number \u002F string \u002F null | No | Non-negative integer repetition interval. A numeric string is also accepted |\n| `params.offsetBeginDateType` | string \u002F number \u002F null | No | Start-date offset unit for the new deal: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.offsetBeginDateValue` | number \u002F string \u002F null | No | Non-negative integer start-date offset for the new deal. A numeric string is also accepted |\n| `params.offsetCloseDateType` | string \u002F number \u002F null | No | Close-date offset unit for the new deal: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.offsetCloseDateValue` | number \u002F string \u002F null | No | Non-negative integer close-date offset for the new deal. A numeric string is also accepted |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dealId\":51,\"isLimit\":\"T\",\"limitRepeat\":1,\"startDate\":\"2027-01-01\",\"params\":{\"mode\":\"multiple\",\"multipleType\":\"month\",\"multipleInterval\":1}}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"dealId\":51,\"isLimit\":\"T\",\"limitRepeat\":1,\"startDate\":\"2027-01-01\",\"params\":{\"mode\":\"multiple\",\"multipleType\":\"month\",\"multipleInterval\":1}}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"dealId\":51,\"isLimit\":\"T\",\"limitRepeat\":1,\"startDate\":\"2027-01-01\",\"params\":{\"mode\":\"multiple\",\"multipleType\":\"month\",\"multipleInterval\":1}}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"dealId\":51,\"isLimit\":\"T\",\"limitRepeat\":1,\"startDate\":\"2027-01-01\",\"params\":{\"mode\":\"multiple\",\"multipleType\":\"month\",\"multipleInterval\":1}}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object | Recurring settings. For the full list of fields, see [Recurring deal fields](.\u002Ffields.md) |\n\n## Response example\n\n201 — the settings were created:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 11,\n    \"dealId\": 53,\n    \"basedId\": 51,\n    \"active\": true,\n    \"categoryId\": null,\n    \"isLimit\": \"T\",\n    \"counterRepeat\": null,\n    \"limitRepeat\": 1,\n    \"limitDate\": null,\n    \"startDate\": \"2027-01-01\",\n    \"nextExecution\": \"2026-12-31T22:00:00.000Z\",\n    \"lastExecution\": null,\n    \"params\": {\n      \"mode\": \"multiple\",\n      \"singleBeforeStartDateValue\": 0,\n      \"singleBeforeStartDateType\": null,\n      \"multipleType\": \"month\",\n      \"multipleInterval\": 1,\n      \"offsetBeginDateType\": null,\n      \"offsetBeginDateValue\": 0,\n      \"offsetCloseDateType\": null,\n      \"offsetCloseDateValue\": 0\n    }\n  }\n}\n```\n\n## Error response example\n\n400 — `dealId` is missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_REQUIRED_FIELDS\",\n    \"message\": \"Body field \\\"dealId\\\" is required to create recurringDeal.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `MISSING_REQUIRED_FIELDS` | `dealId` is missing |\n| 400 | `INVALID_PARAMS` | Invalid deal ID, limit mode, value type or schedule parameter |\n| 400 | `READONLY_FIELD` | A read-only field was passed |\n| 400 | `NESTED_FIELDS_ENVELOPE` | The fields were passed inside a `fields` object. Pass them at the JSON root |\n| 422 | `BITRIX_ERROR` | The template deal already has recurring settings. Message: `Deal already have had recurring settings.` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key has no access to entity methods |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | After the scope check, writing is blocked because the key is in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n| 502 | `BITRIX_UNAVAILABLE` | A network failure, or a Bitrix24 server error with HTTP status 500 or above |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Recurring deal fields](.\u002Ffields.md)\n- [List recurring deals](.\u002Flist.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [MCP](\u002Fdocs\u002Fmcp)\n- [Update recurring settings](.\u002Fupdate.md)\n- [Delete recurring settings](.\u002Fdelete.md)\n- [Deals](\u002Fdocs\u002Fentities\u002Fdeals)\n","## Update recurring settings\n\n`PATCH \u002Fv1\u002Frecurring-deals\u002F:id`\n\nChanges a deal's recurrence settings: lets you stop automatic deal creation or change the schedule and limits.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `id` (path) | number | Yes | Settings ID, a non-negative safe integer. Get IDs from [List recurring deals](.\u002Flist.md) |\n\n## Request fields (body)\n\nPass at least one writable field at the JSON root. For the `params` replacement rules, see the [section overview](..\u002Frecurring-deals.md#before-you-start).\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `active` | boolean \u002F string \u002F null | No | Whether automatic repetition is active. A separate request with `false` stops automatic deal creation. String forms: `\"true\"` \u002F `\"false\"`, `\"yes\"` \u002F `\"no\"`, `\"y\"` \u002F `\"n\"`, `\"1\"` \u002F `\"0\"` |\n| `startDate` | date \u002F null | No | Schedule start date, for example `2027-01-01` |\n| `categoryId` | number \u002F string \u002F null | No | Funnel ID for the generated deals. A numeric string is also accepted. Get IDs from [List pipelines](\u002Fdocs\u002Fentities\u002Fdeal-categories\u002Flist) |\n| `isLimit` | string | No | Repetition limit: `N` — unlimited, `T` — by the `limitRepeat` count, `D` — by the `limitDate` date |\n| `limitRepeat` | number \u002F string \u002F null | No | Integer repetition count for mode `T`. A numeric string is also accepted |\n| `limitDate` | date \u002F null | No | Last allowed date for mode `D` |\n| `params` | object | No | Complete schedule object. The parameters are listed below |\n| `params.mode` | string \u002F number \u002F null | No | Mode: `single` or `multiple`. Numeric codes `1` and `2` are also accepted |\n| `params.singleBeforeStartDateValue` | number \u002F string \u002F null | No | Non-negative integer offset before the start date. A numeric string is also accepted |\n| `params.singleBeforeStartDateType` | string \u002F number \u002F null | No | Offset unit: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.multipleType` | string \u002F number \u002F null | No | Repetition unit: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.multipleInterval` | number \u002F string \u002F null | No | Non-negative integer repetition interval. A numeric string is also accepted |\n| `params.offsetBeginDateType` | string \u002F number \u002F null | No | Start-date offset unit for the new deal: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.offsetBeginDateValue` | number \u002F string \u002F null | No | Non-negative integer start-date offset for the new deal. A numeric string is also accepted |\n| `params.offsetCloseDateType` | string \u002F number \u002F null | No | Close-date offset unit for the new deal: `day`, `week`, `month` or `year`. Numeric unit codes are also accepted |\n| `params.offsetCloseDateValue` | number \u002F string \u002F null | No | Non-negative integer close-date offset for the new deal. A numeric string is also accepted |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"active\":false}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"active\":false}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11', {\n  method: 'PATCH',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"active\":false}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11', {\n  method: 'PATCH',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"active\":false}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object | Recurring settings. For the full field list, see [Recurring deal fields](.\u002Ffields.md) |\n\n## Response example\n\n200 — automatic repetition is disabled:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 11,\n    \"dealId\": 53,\n    \"basedId\": 51,\n    \"active\": false,\n    \"categoryId\": null,\n    \"isLimit\": \"N\",\n    \"counterRepeat\": null,\n    \"limitRepeat\": null,\n    \"limitDate\": null,\n    \"startDate\": \"2026-10-15\",\n    \"nextExecution\": null,\n    \"lastExecution\": null,\n    \"params\": {\n      \"mode\": null,\n      \"singleBeforeStartDateValue\": 0,\n      \"singleBeforeStartDateType\": null,\n      \"multipleType\": null,\n      \"multipleInterval\": 0,\n      \"offsetBeginDateType\": null,\n      \"offsetBeginDateValue\": 0,\n      \"offsetCloseDateType\": null,\n      \"offsetCloseDateValue\": 0\n    }\n  }\n}\n```\n\n## Error response example\n\n404 — the settings were not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Recurring deal is not found.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `EMPTY_UPDATE_BODY` | No field to change was passed |\n| 400 | `INVALID_PARAMS` | Invalid `id`, limit mode, value type or schedule parameter |\n| 400 | `READONLY_FIELD` | An attempt to change `dealId` or a read-only field |\n| 400 | `NESTED_FIELDS_ENVELOPE` | The fields were passed inside a `fields` object. Pass them at the JSON root |\n| 404 | `ENTITY_NOT_FOUND` | The settings were not found. Message: `Recurring deal is not found.` |\n| 404 | `ENTITY_NOT_FOUND` | The update succeeded, but the object is absent on the follow-up read. Message: `recurringDeal \u003Cid> not found` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key has no access to entity methods |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | After the scope check, writing is blocked because the key is in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n| 502 | `BITRIX_UNAVAILABLE` | A network failure, or a Bitrix24 server error with HTTP status 500 or above |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nWriting `params` can enable automatic repetition even when the same request passes `active: false`. To keep repetition off, send a separate request with `active: false` after changing the schedule.\n\n## See also\n\n- [Recurring deal fields](.\u002Ffields.md)\n- [List recurring deals](.\u002Flist.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [MCP](\u002Fdocs\u002Fmcp)\n- [Get recurring settings](.\u002Fget.md)\n- [Create recurring settings](.\u002Fcreate.md)\n- [Delete recurring settings](.\u002Fdelete.md)\n","## Delete recurring settings\n\n`DELETE \u002Fv1\u002Frecurring-deals\u002F:id`\n\nDeletes settings for automatic deal repetition by ID. Deleted settings cannot be restored through the API.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `id` (path) | number | Yes | Settings ID, a non-negative safe integer. Get IDs from [List recurring deals](.\u002Flist.md) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11', {\n  method: 'DELETE',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nif (response.status !== 204) throw new Error(await response.text())\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11', {\n  method: 'DELETE',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },\n})\nif (response.status !== 204) throw new Error(await response.text())\n```\n\n## Response\n\nA successful deletion returns HTTP status `204 No Content` with an empty body. The response code is the success indicator.\n\n## Response example\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Error response example\n\n422 — a connected template deal exists:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Deleting is impossible. Connected recurring deal exists.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_PARAMS` | `id` is not a non-negative safe integer |\n| 404 | `ENTITY_NOT_FOUND` | The settings were not found. Message: `Recurring deal is not found.` |\n| 422 | `BITRIX_ERROR` | A connected template deal exists. Message: `Deleting is impossible. Connected recurring deal exists.` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key has no access to entity methods |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | After the scope check, writing is blocked because the key is in read-only mode |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n| 502 | `BITRIX_UNAVAILABLE` | A network failure, or a Bitrix24 server error with HTTP status 500 or above |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- To stop automatic repetition, [update the settings](.\u002Fupdate.md) with `active: false`.\n- For the order in which to delete the template, the source deal and the generated deals, see the [typical scenario](..\u002Frecurring-deals.md#typical-scenario).\n\n## See also\n\n- [Recurring deal fields](.\u002Ffields.md)\n- [List recurring deals](.\u002Flist.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [MCP](\u002Fdocs\u002Fmcp)\n- [Update recurring settings](.\u002Fupdate.md)\n- [Delete deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fdelete)\n","## Recurring deal fields\n\n`GET \u002Fv1\u002Frecurring-deals\u002Ffields`\n\nReturns field definitions for deal recurrence settings. Use it to check types, required fields and whether a field can be written.\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `refresh` (query) | string | `false` | Supply `true` to refresh field metadata, for example `?refresh=true` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Ffields', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Ffields', {\n  method: 'GET',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data.fields` | object | Complete field definitions: type, `readonly`, `required`, `createOnly`, `nullable`, `enum`, `properties` when present |\n| `data.batch` | string[] | Entity operations listed for batch processing: `create`, `update`, `delete` |\n| `meta.warnings` | object[] | A `fields_partial` warning may be returned when field definitions are partially loaded |\n\n| Field | Type | RO | Description |\n|---|---|---|---|\n| `id` | number | Yes | Setting ID. See [get a setting](.\u002Fget.md). |\n| `dealId` | number | No | Template deal ID. Required and writable only on creation. A regular source deal is copied. See the [deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fget). |\n| `basedId` | number | Yes | Source deal ID. See the [deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fget). May be `null`. |\n| `active` | boolean | No | Whether automatic recurrence is active |\n| `nextExecution` | datetime | Yes | Next execution date. May be `null`. |\n| `lastExecution` | datetime | Yes | Last execution date. May be `null`. |\n| `counterRepeat` | number | Yes | Execution count. May be `null`. |\n| `startDate` | date | No | Schedule start date. May be `null`. |\n| `categoryId` | number | No | Pipeline for created deals. See the [pipeline](\u002Fdocs\u002Fentities\u002Fdeal-categories\u002Fget). May be `null`. |\n| `isLimit` | string | No | Limit mode: `N` — unlimited, `T` — repetition count, `D` — end date |\n| `limitRepeat` | number | No | Maximum repetitions in mode `T`. May be `null`. |\n| `limitDate` | date | No | Last allowed date in mode `D`. May be `null`. |\n| `params` | object | No | Complete schedule parameters. Replaced in full on update |\n| `params.mode` | string | No | Schedule mode. May be `null`. |\n| `params.singleBeforeStartDateValue` | number | No | Single execution offset value |\n| `params.singleBeforeStartDateType` | string | No | Single execution offset type. May be `null`. |\n| `params.multipleType` | string | No | Recurrence period type. May be `null`. |\n| `params.multipleInterval` | number | No | Recurrence interval |\n| `params.offsetBeginDateType` | string | No | Start date offset type. May be `null`. |\n| `params.offsetBeginDateValue` | number | No | Start date offset value |\n| `params.offsetCloseDateType` | string | No | End date offset type. May be `null`. |\n| `params.offsetCloseDateValue` | number | No | End date offset value |\n\n`RO` means the field is read-only.\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"label\": \"Recurring settings ID\",\n        \"description\": \"Recurring settings ID.\"\n      },\n      \"dealId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"createOnly\": true,\n        \"required\": true,\n        \"label\": \"Template deal ID; ordinary source deals are copied on creation\",\n        \"description\": \"Template deal ID; ordinary source deals are copied on creation.\"\n      },\n      \"basedId\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"nullable\": true,\n        \"label\": \"Source deal ID\",\n        \"description\": \"Source deal ID.\"\n      },\n      \"active\": {\n        \"type\": \"boolean\",\n        \"readonly\": false,\n        \"label\": \"Whether automatic repetition is active\",\n        \"description\": \"Whether automatic repetition is active.\"\n      },\n      \"nextExecution\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"nullable\": true,\n        \"label\": \"Next execution date\",\n        \"description\": \"Next execution date.\"\n      },\n      \"lastExecution\": {\n        \"type\": \"datetime\",\n        \"readonly\": true,\n        \"nullable\": true,\n        \"label\": \"Last execution date\",\n        \"description\": \"Last execution date.\"\n      },\n      \"counterRepeat\": {\n        \"type\": \"number\",\n        \"readonly\": true,\n        \"nullable\": true,\n        \"label\": \"Executed repetitions\",\n        \"description\": \"Executed repetitions.\"\n      },\n      \"startDate\": {\n        \"type\": \"date\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"Schedule start date\",\n        \"description\": \"Schedule start date.\"\n      },\n      \"categoryId\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"Pipeline for newly generated deals\",\n        \"description\": \"Pipeline for newly generated deals.\"\n      },\n      \"isLimit\": {\n        \"type\": \"string\",\n        \"readonly\": false,\n        \"label\": \"Repetition limit mode\",\n        \"description\": \"Repetition limit mode.\",\n        \"enum\": [\n          {\n            \"value\": \"N\",\n            \"label\": \"Unlimited\"\n          },\n          {\n            \"value\": \"T\",\n            \"label\": \"Repetition count\"\n          },\n          {\n            \"value\": \"D\",\n            \"label\": \"End date\"\n          }\n        ]\n      },\n      \"limitRepeat\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"Maximum repetition count for T\",\n        \"description\": \"Maximum repetition count for T.\"\n      },\n      \"limitDate\": {\n        \"type\": \"date\",\n        \"readonly\": false,\n        \"nullable\": true,\n        \"label\": \"Last allowed date for D\",\n        \"description\": \"Last allowed date for D.\"\n      },\n      \"params\": {\n        \"type\": \"object\",\n        \"readonly\": false,\n        \"label\": \"Complete schedule parameters; replace as a whole on update\",\n        \"description\": \"Complete schedule parameters; replace as a whole on update.\",\n        \"properties\": {\n          \"mode\": {\n            \"type\": \"string\",\n            \"nullable\": true\n          },\n          \"singleBeforeStartDateValue\": {\n            \"type\": \"number\"\n          },\n          \"singleBeforeStartDateType\": {\n            \"type\": \"string\",\n            \"nullable\": true\n          },\n          \"multipleType\": {\n            \"type\": \"string\",\n            \"nullable\": true\n          },\n          \"multipleInterval\": {\n            \"type\": \"number\"\n          },\n          \"offsetBeginDateType\": {\n            \"type\": \"string\",\n            \"nullable\": true\n          },\n          \"offsetBeginDateValue\": {\n            \"type\": \"number\"\n          },\n          \"offsetCloseDateType\": {\n            \"type\": \"string\",\n            \"nullable\": true\n          },\n          \"offsetCloseDateValue\": {\n            \"type\": \"number\"\n          }\n        }\n      }\n    },\n    \"batch\": [\n      \"create\",\n      \"update\",\n      \"delete\"\n    ]\n  }\n}\n```\n\n## Error response example\n\n401 — API key missing:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_API_KEY\",\n    \"message\": \"API key required. Pass via X-Api-Key header.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` |\n| 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [List recurring deals](.\u002Flist.md)\n- [Get a recurring deal](.\u002Fget.md)\n- [Search recurring deals](.\u002Fsearch.md)\n- [Aggregate recurring deals](.\u002Faggregate.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n","## Search recurring deals\n\n`POST \u002Fv1\u002Frecurring-deals\u002Fsearch`\n\nFinds deal recurrence settings using conditions in the request body. Use it to filter schedules and retrieve selected fields.\n\nFor selections up to 5000 records, use [List recurring deals](.\u002Flist.md). Search accepts its conditions in JSON and can split a wide date filter into intervals.\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `filter` | object | No | Filter by fields from [Recurring deal fields](.\u002Ffields.md).\u003Cbr>[Filtering syntax](\u002Fdocs\u002Ffiltering). Example body field: `\"filter\":{\"active\":false}` |\n| `sort` | string \u002F object \u002F string[] | No | Sort fields. `id` sorts ascending, `-id` descending |\n| `order` | object | No | Alternative to `sort`, for example `{\"id\":\"desc\"}` |\n| `select` | string \u002F string[] | No | Response fields. A comma-separated string or an array of names |\n| `limit` | number \u002F string | No | Selection size, default 50, maximum 5000. A numeric string is also accepted |\n| `offset` | number | No | Offset from the start of the selection. A value greater than zero is incompatible with automatic splitting of a date range wider than 14 days. Use `autoWindow: false` with `sort: \"id\"` for pagination |\n| `autoWindow` | boolean | No | Set to `false` to disable automatic splitting of a wide date filter into windows |\n| `withTotal` | boolean | No | Requests the total count in `meta.total` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filter\":{\"active\":false},\"sort\":\"id\",\"select\":[\"id\",\"dealId\",\"basedId\",\"active\",\"nextExecution\",\"lastExecution\",\"counterRepeat\",\"startDate\",\"categoryId\",\"isLimit\",\"limitRepeat\",\"limitDate\",\"params\"],\"limit\":2,\"withTotal\":true}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"filter\":{\"active\":false},\"sort\":\"id\",\"select\":[\"id\",\"dealId\",\"basedId\",\"active\",\"nextExecution\",\"lastExecution\",\"counterRepeat\",\"startDate\",\"categoryId\",\"isLimit\",\"limitRepeat\",\"limitDate\",\"params\"],\"limit\":2,\"withTotal\":true}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fsearch', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"filter\":{\"active\":false},\"sort\":\"id\",\"select\":[\"id\",\"dealId\",\"basedId\",\"active\",\"nextExecution\",\"lastExecution\",\"counterRepeat\",\"startDate\",\"categoryId\",\"isLimit\",\"limitRepeat\",\"limitDate\",\"params\"],\"limit\":2,\"withTotal\":true}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fsearch', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"filter\":{\"active\":false},\"sort\":\"id\",\"select\":[\"id\",\"dealId\",\"basedId\",\"active\",\"nextExecution\",\"lastExecution\",\"counterRepeat\",\"startDate\",\"categoryId\",\"isLimit\",\"limitRepeat\",\"limitDate\",\"params\"],\"limit\":2,\"withTotal\":true}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object[] | Recurrence settings. See [recurring deal fields](.\u002Ffields.md) |\n| `meta.total` | number | Total matching settings, when returned |\n| `meta.hasMore` | boolean | Whether more records are available |\n| `meta.durationMs` | number | Execution time in milliseconds, when returned |\n| `meta.warnings` | object[] | Warnings, when returned. Unknown `select` fields can be ignored in a successful request |\n| `meta.autoWindowed` | boolean | Whether date windowing was applied |\n| `meta.windowCount` | number | Number of date intervals, when windowing is applied |\n| `meta.windowErrors` | number | Number of failed intervals, when failures occur |\n| `meta.windowErrorSample` | object | First interval error with code and message, on partial failure |\n| `meta.pageErrorSample` | object | Sample subpage error when the returned selection is incomplete |\n\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 1,\n      \"dealId\": 575,\n      \"basedId\": 573,\n      \"active\": false,\n      \"nextExecution\": null,\n      \"lastExecution\": \"2020-06-16T22:00:00.000Z\",\n      \"counterRepeat\": 2,\n      \"startDate\": \"2020-06-15\",\n      \"categoryId\": 1,\n      \"isLimit\": \"T\",\n      \"limitRepeat\": 2,\n      \"limitDate\": null,\n      \"params\": {\n        \"mode\": \"multiple\",\n        \"singleBeforeStartDateValue\": 0,\n        \"singleBeforeStartDateType\": \"day\",\n        \"multipleType\": \"day\",\n        \"multipleInterval\": 1,\n        \"offsetBeginDateType\": \"day\",\n        \"offsetBeginDateValue\": 1,\n        \"offsetCloseDateType\": \"day\",\n        \"offsetCloseDateValue\": 1\n      }\n    },\n    {\n      \"id\": 3,\n      \"dealId\": 3865,\n      \"basedId\": 3863,\n      \"active\": false,\n      \"nextExecution\": null,\n      \"lastExecution\": \"2021-01-12T22:00:00.000Z\",\n      \"counterRepeat\": 2,\n      \"startDate\": \"2021-01-14\",\n      \"categoryId\": 0,\n      \"isLimit\": \"D\",\n      \"limitRepeat\": null,\n      \"limitDate\": \"2021-01-13\",\n      \"params\": {\n        \"mode\": \"single\",\n        \"singleBeforeStartDateValue\": 1,\n        \"singleBeforeStartDateType\": \"day\",\n        \"multipleType\": \"day\",\n        \"multipleInterval\": 1,\n        \"offsetBeginDateType\": \"day\",\n        \"offsetBeginDateValue\": 0,\n        \"offsetCloseDateType\": \"day\",\n        \"offsetCloseDateValue\": 0\n      }\n    }\n  ],\n  \"meta\": {\n    \"total\": 4,\n    \"hasMore\": true,\n    \"durationMs\": 123\n  }\n}\n```\n\n## Error response example\n\n400 — unknown filter field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'madeUp' for entity 'recurring-deals'. Available: id, dealId, basedId, active, nextExecution, lastExecution, counterRepeat, startDate, categoryId, isLimit, limitRepeat, limitDate\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_REQUEST` | The request body is not a JSON object |\n| 400 | `INVALID_LIMIT` | `limit` cannot be interpreted as a finite number. Numbers and numeric strings are accepted |\n| 400 | `INVALID_SELECT_TYPE` | `select` is not a string or an array of strings |\n| 400 | `INVALID_SORT_TYPE` | `sort` is not a string, object or array of strings |\n| 400 | `UNKNOWN_FILTER_FIELD` | The filter references an unknown field. See the error message and [field definitions](.\u002Ffields.md) |\n| 400 | `INVALID_FILTER_FIELD` | A field name starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition using `$or` or `$and` |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions map to the same filter condition. Supply only one |\n| 400 | `INVALID_SORT_FIELD` | Sorting uses a forbidden name: `__proto__`, `constructor` or `prototype` |\n| 400 | `UNKNOWN_SORT_FIELD` | Sorting references an unknown field |\n| 400 | `INVALID_SORT_DIRECTION` | A sort direction is not one of the strings `asc`, `desc`, `ASC`, `DESC` or the numbers `1`, `-1` |\n| 400 | `INVALID_FILTER_SHAPE` | `filter` is not an object |\n| 400 | `UNSTABLE_OFFSET_PAGINATION` | `offset > 0` is combined with automatic splitting of a date range wider than 14 days. Use `autoWindow: false` with `sort: \"id\"` for pagination |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` |\n| 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nThe response can include settings with `active: false`. To retrieve active schedules only, filter by `active: true`.\n\n## See also\n\n- [List recurring deals](.\u002Flist.md)\n- [Get a recurring deal](.\u002Fget.md)\n- [Recurring deal fields](.\u002Ffields.md)\n- [Aggregate recurring deals](.\u002Faggregate.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n","## Batch operations\n\n`POST \u002Fv1\u002Frecurring-deals\u002Fbatch`\n\nRuns several operations of the same type on recurring deal settings.\n\n## Parameters\n\nThere are no path parameters. The batch payload is passed in the request body.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `action` | string | yes | Operation for the whole batch: `create`, `update`, `delete`, `list`, `get` or `fields` |\n| `items` | object[] | no | Required for `create` and `update`. A non-empty array of objects with [create](.\u002Fcreate.md) or [update](.\u002Fupdate.md) fields |\n| `items[].id` | number \u002F string | no | Required for `update`. Setting ID from the [recurring deals list](.\u002Flist.md) |\n| `ids` | array | no | Required for `delete`. A non-empty array of setting IDs from the [recurring deals list](.\u002Flist.md) |\n| `calls` | object[] | no | Required for `list`, `get` and `fields`. A non-empty array of subrequests |\n| `calls[].params` | object | no | Subrequest parameters. For `list` — [list parameters](.\u002Flist.md), for `get` — the setting ID, for `fields` you can pass `{}` |\n| `calls[].params.id` | number \u002F string | no | Required for `get`. Setting ID from the [recurring deals list](.\u002Flist.md) |\n\nThe batch size is limited by platform settings. By default, up to 500 items for `create`, `update`, `delete` and up to 50 subrequests for `list`, `get`, `fields`.\n\nIn write batches, `null` is not passed for `active`, `startDate`, `categoryId`, `limitRepeat`, `limitDate` and the nested `params` fields. To pass `null` explicitly, use [create a single setting](.\u002Fcreate.md) or [update a single setting](.\u002Fupdate.md).\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fbatch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"action\":\"update\",\"items\":[{\"id\":11,\"active\":false}]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fbatch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"action\":\"update\",\"items\":[{\"id\":11,\"active\":false}]}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fbatch', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"action\":\"update\",\"items\":[{\"id\":11,\"active\":false}]}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Fbatch', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"action\":\"update\",\"items\":[{\"id\":11,\"active\":false}]}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n### Create, update and delete\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `success` | boolean | yes | `true` if the batch is processed. Check the result of each item separately |\n| `data` | object | yes | Batch results |\n| `data.results` | object[] | yes | Results in the order of the request items |\n| `data.results[].index` | number | yes | Zero-based index of the item in the source array |\n| `data.results[].success` | boolean | yes | Whether the operation on this item succeeded |\n| `data.results[].id` | number \u002F string | no | ID of the created setting, or the source ID on update and delete. Get the setting: [by ID](.\u002Fget.md) |\n| `data.results[].error` | string | no | Refusal code of the item. Can be an empty string, so check `success` |\n| `data.results[].message` | string | no | Refusal message of the item |\n| `data.summary` | object | yes | Batch summary |\n| `data.summary.total` | number | yes | Number of processed items |\n| `data.summary.succeeded` | number | yes | Number of successful operations |\n| `data.summary.failed` | number | yes | Number of refused operations |\n\nAn error in a single operation is returned in `data.results`, and the HTTP status of the batch stays `200`.\n\n### Read\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `success` | boolean | yes | `true` if the batch is processed |\n| `data` | object[] | yes | Results in the order of the subrequests |\n| `data[].data` | object \u002F array \u002F null | no | Successful result: for `list` — an array of settings, for `get` — a setting or `null`, for `fields` — a map of field metadata. Setting fields: [Recurring deal fields](.\u002Ffields.md) |\n| `data[].total` | number | no | Total number of records for `list` |\n| `data[].hasMore` | boolean | no | Whether there is a next page for `list` |\n| `data[].meta` | object | no | List warnings |\n| `data[].error` | object | no | Refusal of a single subrequest instead of `data` |\n| `data[].error.code` | string | no | Refusal code of the subrequest |\n| `data[].error.message` | string | no | Refusal message of the subrequest |\n\nFor `fields`, the map keys keep the original Bitrix24 field names, for example `ID` and `DEAL_ID`. For `list` and `get`, the setting fields use Vibecode API names.\n\nA refusal of one read subrequest does not stop the rest. The HTTP status of the batch stays `200`.\n\n## Response example\n\n200 — the setting from the example is updated:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"results\": [\n      {\n        \"index\": 0,\n        \"success\": true,\n        \"id\": 11\n      }\n    ],\n    \"summary\": {\n      \"total\": 1,\n      \"succeeded\": 1,\n      \"failed\": 0\n    }\n  }\n}\n```\n\nFor reads the structure differs. Request body: `{\"action\":\"list\",\"calls\":[{\"params\":{\"filter\":{\"id\":11},\"select\":[\"id\",\"active\"]}}]}`.\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"data\": [\n        {\n          \"id\": 11,\n          \"active\": false\n        }\n      ],\n      \"total\": 1,\n      \"hasMore\": false\n    }\n  ]\n}\n```\n\n## Error response example\n\n400 — an unknown operation is passed:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_BATCH_ACTION\",\n    \"message\": \"Action must be one of: create, update, delete, list, get, fields\"\n  }\n}\n```\n\n## Errors\n\nThe table describes refusals of the whole request. Refusals of individual operations are in the batch results.\n\nWrite batches have no rollback. If the request fails after commands have been sent, for example with `502 BITRIX_UNAVAILABLE` or `503 BITRIX_TIMEOUT`, some operations may have completed and the outcome of others may be unknown. The error response does not include the accumulated successful results. Check the state of the records before retrying: repeating a create request may produce duplicates.\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_BATCH_ACTION` | `action` is missing or an unknown operation is passed |\n| 400 | `BATCH_ITEM_VALIDATION` | No non-empty array is passed for the selected operation, a required item field is missing, or an item contains an invalid value or a read-only field |\n| 400 | `BATCH_LIMIT_EXCEEDED` | The batch size limit is exceeded. The current limit is given in `error.message` |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key has no access to entity data |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key passed the scope check, but its mode forbids `create`, `update` or `delete` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the whole batch |\n| 422 | `BITRIX_ERROR` | A Bitrix24 business refusal at the level of the whole batch. The reason is in `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n| 502 | `BITRIX_UNAVAILABLE` | A network failure or a Bitrix24 server error with HTTP status 500 and above |\n| 429 | `RATE_LIMITED` | The request limit is exceeded. The wait time is in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Create a setting](.\u002Fcreate.md)\n- [Update a setting](.\u002Fupdate.md)\n- [Delete a setting](.\u002Fdelete.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [MCP for AI](\u002Fdocs\u002Fmcp)\n- [Deals](..\u002Fdeals.md)\n","## Aggregate\n\n`POST \u002Fv1\u002Frecurring-deals\u002Faggregate`\n\nCounts deal recurrence settings and computes numeric aggregates using a filter. Use it to analyse execution counts and repetition limits.\n\n## Standard fields\n\n| Field | Purpose |\n|---|---|\n| `counterRepeat` | Execution count. Meaningful for `sum`, `avg`, `min`, `max` |\n| `limitRepeat` | Repetition count limit. Meaningful for numeric functions |\n| `id`, `dealId`, `basedId`, `categoryId` | Identifiers. Accepted by numeric functions, their sum does not describe execution counts |\n\nStandard fields are unavailable for `groupBy`: recurring deals can be grouped only by UF fields. A request with a standard field returns `INVALID_PARAMS` with an empty list of available fields.\n\n## Custom fields (UF)\n\nThe method accepts UF fields of types `integer`, `double`, `money` for numeric functions, and any UF type for `groupBy` and filtering. Names use `UF_CRM_*` or `ufCrm_*`. For an unknown numeric UF field, `INVALID_PARAMS` lists available numeric fields. To use a UF field, configure it in your Bitrix24 account.\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `aggregate` | object[] | No | Up to 5 expressions. Default: `count` over `*` |\n| `aggregate[].field` | string | Yes | Expression field: `*` for `count`, a numeric field for `sum`, `avg`, `min`, `max` |\n| `aggregate[].function` | string | Yes | Function: `count`, `sum`, `avg`, `min`, `max` |\n| `filter` | object | No | Conditions using the [filter syntax](\u002Fdocs\u002Ffiltering) |\n| `groupBy` | string \u002F string[] | No | Up to 5 fields. Only UF fields that exist in the Bitrix24 account: standard fields cannot be used for grouping |\n| `groupOrderBy` | object[] | No | Group sorting. Only with `groupBy` |\n| `groupOrderBy[].field` | string | Yes | A grouping key, `count`, or a requested result such as `counterRepeat:sum` |\n| `groupOrderBy[].direction` | string | No | Direction: `asc` or `desc`. Default: `desc` |\n| `groupLimit` | number | No | With `groupBy`: an integer from 1 to 1000 |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"aggregate\":[{\"field\":\"counterRepeat\",\"function\":\"sum\"},{\"field\":\"counterRepeat\",\"function\":\"avg\"}],\"filter\":{\"active\":true}}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"aggregate\":[{\"field\":\"counterRepeat\",\"function\":\"sum\"},{\"field\":\"counterRepeat\",\"function\":\"avg\"}],\"filter\":{\"active\":true}}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Faggregate', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"aggregate\":[{\"field\":\"counterRepeat\",\"function\":\"sum\"},{\"field\":\"counterRepeat\",\"function\":\"avg\"}],\"filter\":{\"active\":true}}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002Faggregate', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({\"aggregate\":[{\"field\":\"counterRepeat\",\"function\":\"sum\"},{\"field\":\"counterRepeat\",\"function\":\"avg\"}],\"filter\":{\"active\":true}}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\nFor a `groupBy` array, supply up to 5 existing UF field names.\n\n## Other scenarios\n\nThe blocks below are request bodies.\n\nCount all settings:\n\n```json\n{}\n```\n\nCount with a filter:\n\n```json\n{\n  \"filter\": {\n    \"id\": 1\n  },\n  \"aggregate\": [\n    {\n      \"field\": \"*\",\n      \"function\": \"count\"\n    }\n  ]\n}\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded |\n| `data` | object | The aggregation result. Its fields are the `data.*` rows below |\n| `data.count` | number | Total matching records |\n| `data.aggregates` | object | Results by field and function |\n| `data.aggregates.\u003Cfield>.truncated` | boolean | Incomplete calculation marker, when set |\n| `data.groups` | object[] | Groups, only with `groupBy` |\n| `data.groups[].count` | number | Read records in a group |\n| `data.groups[].aggregates` | object | Group results by field and function |\n| `data.groups[].truncated` | boolean | Incomplete group marker, when set |\n| `data.meta.totalRecords` | number | Total matching records |\n| `data.meta.recordsProcessed` | number | Number of records read, an optional field |\n| `data.meta.truncated` | boolean | Whether the calculation uses an incomplete selection |\n| `data.meta.recordsShortfall` | number | Missing records: `totalRecords - recordsProcessed`. Also returned at the 5000-record cap |\n| `data.meta.pageErrorSample` | object | Sample subpage error when reading is interrupted |\n| `data.meta.warnings` | object[] | Contains `AGGREGATE_TRUNCATED` for an incomplete selection |\n| `data.meta.groupTotal` | number | Number of groups before the `groupLimit` cap |\n| `data.meta.groupsTruncated` | boolean | Whether the group list was limited by `groupLimit` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 2,\n    \"aggregates\": {\n      \"counterRepeat\": {\n        \"sum\": 699,\n        \"avg\": 349.5\n      }\n    },\n    \"meta\": {\n      \"totalRecords\": 2,\n      \"recordsProcessed\": 2,\n      \"truncated\": false\n    }\n  }\n}\n```\n\nWithout `groupBy`, `data.groups` is absent from the response.\n\n## Error response example\n\n400 — unknown numeric aggregation field:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Field 'UF_CRM_NOT_REAL' not found. Available numeric fields: id, dealId, basedId, counterRepeat, categoryId, limitRepeat.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_PARAMS` | `aggregate` is not an array or the array is empty |\n| 400 | `INVALID_PARAMS` | The `aggregate` array contains more than 5 expressions |\n| 400 | `INVALID_PARAMS` | An unknown or missing function. Allowed: `count`, `sum`, `avg`, `min`, `max` |\n| 400 | `INVALID_PARAMS` | The field for `count` is not `*` |\n| 400 | `INVALID_PARAMS` | A numeric function has no field or uses `*` |\n| 400 | `INVALID_PARAMS` | A standard field does not have type `number` |\n| 400 | `INVALID_PARAMS` | A UF field has a non-numeric type. The message names the UF type |\n| 400 | `INVALID_PARAMS` | The field was not found. The message lists available standard and custom numeric fields |\n| 400 | `INVALID_PARAMS` | Separate `op`, `field` or `function` values are supplied without an `aggregate` array |\n| 400 | `INVALID_PARAMS` | `groupBy` is not a string or an array of strings |\n| 400 | `INVALID_PARAMS` | The `groupBy` array contains more than 5 fields |\n| 400 | `INVALID_PARAMS` | `groupBy` contains a standard field: recurring deals cannot be grouped by standard fields |\n| 400 | `INVALID_PARAMS` | `groupBy` uses a reserved name: `count`, `aggregates`, `meta` or `groups` |\n| 400 | `INVALID_PARAMS` | `groupOrderBy` is supplied without `groupBy` |\n| 400 | `INVALID_PARAMS` | `groupLimit` is supplied without `groupBy` |\n| 400 | `INVALID_PARAMS` | `groupOrderBy` is not an array |\n| 400 | `INVALID_PARAMS` | A `groupOrderBy` entry is not an object with a non-empty `field` string |\n| 400 | `INVALID_PARAMS` | The `groupOrderBy` direction is neither `asc` nor `desc` |\n| 400 | `INVALID_PARAMS` | A sort key in `\u003Cfield>:\u003Cfunction>` format is not requested in `aggregate` |\n| 400 | `INVALID_PARAMS` | A group sort field is not a `groupBy` key, `count` or a numeric result key |\n| 400 | `INVALID_PARAMS` | `groupLimit` is not an integer from 1 to 1000 |\n| 400 | `UNKNOWN_FILTER_FIELD` | The filter references an unknown field. See the error message and [field definitions](.\u002Ffields.md) |\n| 400 | `INVALID_FILTER_FIELD` | A field name starts with the unsupported prefix `@` or `!@` |\n| 400 | `INVALID_FILTER_OPERATOR` | An unknown operator, an empty condition object, or a logical condition using `$or` or `$and` |\n| 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Two conditions map to the same filter condition. Supply only one |\n| 400 | `INVALID_FILTER_SHAPE` | `filter` is not an object |\n| 422 | `AGGREGATION_LIMIT_EXCEEDED` | The numeric or grouped selection exceeds 5000 records and rejection before reading records is enabled |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` |\n| 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established |\n| 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header |\n\nFor the full list of common API errors, see [Error codes](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nWithout `groupBy` and without numeric functions, the method returns a count without reading records: `recordsProcessed: 0`, `truncated: false`. A `count` request with `groupBy` requires records to be read. Numeric functions use the records read, up to 5000. Narrow the filter for an exact result.\n\n`data.meta.truncated` becomes `true` if fewer records were read than the reported total, or a subpage error interrupted reading. A shortfall can occur below the 5000-record cap. The response always includes `recordsShortfall` or `pageErrorSample` in this case, and field and group results are marked as `truncated`.\n\n## See also\n\n- [List recurring deals](.\u002Flist.md)\n- [Get a recurring deal](.\u002Fget.md)\n- [Recurring deal fields](.\u002Ffields.md)\n- [Search recurring deals](.\u002Fsearch.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n","## Create a deal from a template\n\n`POST \u002Fv1\u002Frecurring-deals\u002F:id\u002Fexpose`\n\nCreates a deal immediately from a recurring deal template. Use it for manual creation when you do not need to wait for the next scheduled run.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `id` (path) | number | yes | — | Setting ID from the [recurring deals list](.\u002Flist.md). A positive integer within the safe range |\n\n## Request fields (body)\n\nThe request body can be empty or `{}`. No fields are accepted.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\u002Fexpose\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\u002Fexpose\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\u002Fexpose', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Frecurring-deals\u002F11\u002Fexpose', {\n  method: 'POST',\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({}),\n})\nconst result = await response.json()\nif (!result.success) throw new Error(result.error.message)\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `success` | boolean | yes | `true` on successful creation |\n| `data` | object | yes | The created deal |\n| `data.dealId` | number | yes | ID of the new deal. Get the deal: [by ID](..\u002Fdeals\u002Fget.md) |\n| `data.links` | object | yes | Links to the created deal |\n| `data.links.deal` | string | yes | Relative path to the deal resource: `\u002Fv1\u002Fdeals\u002F:dealId` |\n\n## Response example\n\n201 — the deal is created:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"dealId\": 52,\n    \"links\": {\n      \"deal\": \"\u002Fv1\u002Fdeals\u002F52\"\n    }\n  }\n}\n```\n\n## Error response example\n\n400 — a field is passed in the request body:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"This action accepts no fields\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `INVALID_PARAMS` | `id` is not a positive integer within the safe range |\n| 400 | `INVALID_PARAMS` | The request body contains fields, or is `null`, an array or a scalar instead of an object. Message: `This action accepts no fields` |\n| 404 | `ENTITY_NOT_FOUND` | A setting with this ID is not found |\n| 502 | `BITRIX_RESPONSE_INVALID` | The Bitrix24 response contains no valid ID of the created deal |\n| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | A management key has no access to entity data |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key passed the scope check, but its mode forbids creating a deal |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is not passed |\n| 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |\n| 422 | `BITRIX_ERROR` | A Bitrix24 business refusal or a plan restriction. The reason is in `error.message` |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n| 502 | `BITRIX_UNAVAILABLE` | A network failure or a Bitrix24 server error with HTTP status 500 and above |\n| 429 | `RATE_LIMITED` | The request limit is exceeded. The wait time is in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Get a setting](.\u002Fget.md)\n- [Update a setting](.\u002Fupdate.md)\n- [Recurring deals](..\u002Frecurring-deals.md)\n- [MCP for AI](\u002Fdocs\u002Fmcp)\n- [Get a deal](..\u002Fdeals\u002Fget.md)\n- [Deals](..\u002Fdeals.md)\n",1795000369732]