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

Create recurring settings

POST /v1/recurring-deals

Creates settings for automatic deal repetition.

Request fields (body)

Pass the fields at the JSON root.

Field Type Required Description
FielddealId Typenumber / string RequiredYes DescriptionSource deal ID, a positive integer. A numeric string is also accepted. Get IDs from List deals
Fieldactive Typeboolean / string / null RequiredNo DescriptionWhether automatic repetition is active. 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 POST "https://vibecode.bitrix24.com/v1/recurring-deals" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dealId":51,"isLimit":"T","limitRepeat":1,"startDate":"2027-01-01","params":{"mode":"multiple","multipleType":"month","multipleInterval":1}}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/recurring-deals" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dealId":51,"isLimit":"T","limitRepeat":1,"startDate":"2027-01-01","params":{"mode":"multiple","multipleType":"month","multipleInterval":1}}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"dealId":51,"isLimit":"T","limitRepeat":1,"startDate":"2027-01-01","params":{"mode":"multiple","multipleType":"month","multipleInterval":1}}),
})
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', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"dealId":51,"isLimit":"T","limitRepeat":1,"startDate":"2027-01-01","params":{"mode":"multiple","multipleType":"month","multipleInterval":1}}),
})
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 list of fields, see Recurring deal fields

Response example

201 — the settings were created:

JSON 
{
  "success": true,
  "data": {
    "id": 11,
    "dealId": 53,
    "basedId": 51,
    "active": true,
    "categoryId": null,
    "isLimit": "T",
    "counterRepeat": null,
    "limitRepeat": 1,
    "limitDate": null,
    "startDate": "2027-01-01",
    "nextExecution": "2026-12-31T22:00:00.000Z",
    "lastExecution": null,
    "params": {
      "mode": "multiple",
      "singleBeforeStartDateValue": 0,
      "singleBeforeStartDateType": null,
      "multipleType": "month",
      "multipleInterval": 1,
      "offsetBeginDateType": null,
      "offsetBeginDateValue": 0,
      "offsetCloseDateType": null,
      "offsetCloseDateValue": 0
    }
  }
}

Error response example

400 — dealId is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"dealId\" is required to create recurringDeal."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptiondealId is missing
HTTP400 CodeINVALID_PARAMS DescriptionInvalid deal ID, limit mode, value type or schedule parameter
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe fields were passed inside a fields object. Pass them at the JSON root
HTTP422 CodeBITRIX_ERROR DescriptionThe template deal already has recurring settings. Message: Deal already have had recurring settings.
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.

See also