For AI agents: markdown of this page — /docs-content-en/entities/recurring-deals/update.md documentation index — /llms.txt

Update recurring settings

PATCH /v1/recurring-deals/:id

Changes a deal's recurrence settings: lets you stop automatic deal creation or change the schedule and limits.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber RequiredYes DescriptionSettings ID, a non-negative safe integer. Get IDs from List recurring deals

Request fields (body)

Pass at least one writable field at the JSON root. For the params replacement rules, see the section overview.

Field Type Required Description
Fieldactive Typeboolean / string / null RequiredNo DescriptionWhether automatic repetition is active. A separate request with false stops automatic deal creation. String forms: "true" / "false", "yes" / "no", "y" / "n", "1" / "0"
FieldstartDate Typedate / null RequiredNo DescriptionSchedule start date, for example 2027-01-01
FieldcategoryId Typenumber / string / null RequiredNo DescriptionFunnel ID for the generated deals. A numeric string is also accepted. Get IDs from List pipelines
FieldisLimit Typestring RequiredNo DescriptionRepetition limit: N — unlimited, T — by the limitRepeat count, D — by the limitDate date
FieldlimitRepeat Typenumber / string / null RequiredNo DescriptionInteger repetition count for mode T. A numeric string is also accepted
FieldlimitDate Typedate / null RequiredNo DescriptionLast allowed date for mode D
Fieldparams Typeobject RequiredNo DescriptionComplete schedule object. The parameters are listed below
Fieldparams.mode Typestring / number / null RequiredNo DescriptionMode: single or multiple. Numeric codes 1 and 2 are also accepted
Fieldparams.singleBeforeStartDateValue Typenumber / string / null RequiredNo DescriptionNon-negative integer offset before the start date. A numeric string is also accepted
Fieldparams.singleBeforeStartDateType Typestring / number / null RequiredNo DescriptionOffset unit: day, week, month or year. Numeric unit codes are also accepted
Fieldparams.multipleType Typestring / number / null RequiredNo DescriptionRepetition unit: day, week, month or year. Numeric unit codes are also accepted
Fieldparams.multipleInterval Typenumber / string / null RequiredNo DescriptionNon-negative integer repetition interval. A numeric string is also accepted
Fieldparams.offsetBeginDateType Typestring / number / null RequiredNo DescriptionStart-date offset unit for the new deal: day, week, month or year. Numeric unit codes are also accepted
Fieldparams.offsetBeginDateValue Typenumber / string / null RequiredNo DescriptionNon-negative integer start-date offset for the new deal. A numeric string is also accepted
Fieldparams.offsetCloseDateType Typestring / number / null RequiredNo DescriptionClose-date offset unit for the new deal: day, week, month or year. Numeric unit codes are also accepted
Fieldparams.offsetCloseDateValue Typenumber / string / null RequiredNo DescriptionNon-negative integer close-date offset for the new deal. A numeric string is also accepted

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/recurring-deals/11" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/recurring-deals/11" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/11', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"active":false}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/11', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"active":false}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionWhether the request succeeded
Fielddata Typeobject DescriptionRecurring settings. For the full field list, see Recurring deal fields

Response example

200 — automatic repetition is disabled:

JSON 
{
  "success": true,
  "data": {
    "id": 11,
    "dealId": 53,
    "basedId": 51,
    "active": false,
    "categoryId": null,
    "isLimit": "N",
    "counterRepeat": null,
    "limitRepeat": null,
    "limitDate": null,
    "startDate": "2026-10-15",
    "nextExecution": null,
    "lastExecution": null,
    "params": {
      "mode": null,
      "singleBeforeStartDateValue": 0,
      "singleBeforeStartDateType": null,
      "multipleType": null,
      "multipleInterval": 0,
      "offsetBeginDateType": null,
      "offsetBeginDateValue": 0,
      "offsetCloseDateType": null,
      "offsetCloseDateValue": 0
    }
  }
}

Error response example

404 — the settings were not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Recurring deal is not found."
  }
}

Errors

HTTP Code Description
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionNo field to change was passed
HTTP400 CodeINVALID_PARAMS DescriptionInvalid id, limit mode, value type or schedule parameter
HTTP400 CodeREADONLY_FIELD DescriptionAn attempt to change dealId or a read-only field
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe fields were passed inside a fields object. Pass them at the JSON root
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe settings were not found. Message: Recurring deal is not found.
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe update succeeded, but the object is absent on the follow-up read. Message: recurringDeal <id> not found
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionA management key has no access to entity methods
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionAfter the scope check, writing is blocked because the key is in read-only mode
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the operation or a plan restriction applies. See error.message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionA network failure, or a Bitrix24 server error with HTTP status 500 or above
HTTP429 CodeRATE_LIMITED DescriptionThe request rate limit was exceeded. Retry after the interval in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

Writing 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.

See also