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

Batch operations

POST /v1/recurring-deals/batch

Runs several operations of the same type on recurring deal settings.

Parameters

There are no path parameters. The batch payload is passed in the request body.

Request fields (body)

Field Type Required Description
Fieldaction Typestring Requiredyes DescriptionOperation for the whole batch: create, update, delete, list, get or fields
Fielditems Typeobject[] Requiredno DescriptionRequired for create and update. A non-empty array of objects with create or update fields
Fielditems[].id Typenumber / string Requiredno DescriptionRequired for update. Setting ID from the recurring deals list
Fieldids Typearray Requiredno DescriptionRequired for delete. A non-empty array of setting IDs from the recurring deals list
Fieldcalls Typeobject[] Requiredno DescriptionRequired for list, get and fields. A non-empty array of subrequests
Fieldcalls[].params Typeobject Requiredno DescriptionSubrequest parameters. For list — list parameters, for get — the setting ID, for fields you can pass {}
Fieldcalls[].params.id Typenumber / string Requiredno DescriptionRequired for get. Setting ID from the recurring deals list

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

In 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 or update a single setting.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/recurring-deals/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","items":[{"id":11,"active":false}]}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/recurring-deals/batch" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","items":[{"id":11,"active":false}]}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/batch', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"action":"update","items":[{"id":11,"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/batch', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"action":"update","items":[{"id":11,"active":false}]}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Response fields

Create, update and delete

Field Type Required Description
Fieldsuccess Typeboolean Requiredyes Descriptiontrue if the batch is processed. Check the result of each item separately
Fielddata Typeobject Requiredyes DescriptionBatch results
Fielddata.results Typeobject[] Requiredyes DescriptionResults in the order of the request items
Fielddata.results[].index Typenumber Requiredyes DescriptionZero-based index of the item in the source array
Fielddata.results[].success Typeboolean Requiredyes DescriptionWhether the operation on this item succeeded
Fielddata.results[].id Typenumber / string Requiredno DescriptionID of the created setting, or the source ID on update and delete. Get the setting: by ID
Fielddata.results[].error Typestring Requiredno DescriptionRefusal code of the item. Can be an empty string, so check success
Fielddata.results[].message Typestring Requiredno DescriptionRefusal message of the item
Fielddata.summary Typeobject Requiredyes DescriptionBatch summary
Fielddata.summary.total Typenumber Requiredyes DescriptionNumber of processed items
Fielddata.summary.succeeded Typenumber Requiredyes DescriptionNumber of successful operations
Fielddata.summary.failed Typenumber Requiredyes DescriptionNumber of refused operations

An error in a single operation is returned in data.results, and the HTTP status of the batch stays 200.

Read

Field Type Required Description
Fieldsuccess Typeboolean Requiredyes Descriptiontrue if the batch is processed
Fielddata Typeobject[] Requiredyes DescriptionResults in the order of the subrequests
Fielddata[].data Typeobject / array / null Requiredno DescriptionSuccessful 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
Fielddata[].total Typenumber Requiredno DescriptionTotal number of records for list
Fielddata[].hasMore Typeboolean Requiredno DescriptionWhether there is a next page for list
Fielddata[].meta Typeobject Requiredno DescriptionList warnings
Fielddata[].error Typeobject Requiredno DescriptionRefusal of a single subrequest instead of data
Fielddata[].error.code Typestring Requiredno DescriptionRefusal code of the subrequest
Fielddata[].error.message Typestring Requiredno DescriptionRefusal message of the subrequest

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

A refusal of one read subrequest does not stop the rest. The HTTP status of the batch stays 200.

Response example

200 — the setting from the example is updated:

JSON 
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "success": true,
        "id": 11
      }
    ],
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0
    }
  }
}

For reads the structure differs. Request body: {"action":"list","calls":[{"params":{"filter":{"id":11},"select":["id","active"]}}]}.

JSON 
{
  "success": true,
  "data": [
    {
      "data": [
        {
          "id": 11,
          "active": false
        }
      ],
      "total": 1,
      "hasMore": false
    }
  ]
}

Error response example

400 — an unknown operation is passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_BATCH_ACTION",
    "message": "Action must be one of: create, update, delete, list, get, fields"
  }
}

Errors

The table describes refusals of the whole request. Refusals of individual operations are in the batch results.

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

HTTP Code Description
HTTP400 CodeINVALID_BATCH_ACTION Descriptionaction is missing or an unknown operation is passed
HTTP400 CodeBATCH_ITEM_VALIDATION DescriptionNo 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
HTTP400 CodeBATCH_LIMIT_EXCEEDED DescriptionThe batch size limit is exceeded. The current limit is given in error.message
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionA management key has no access to entity data
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key passed the scope check, but its mode forbids create, update or delete
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is not passed
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the whole batch
HTTP422 CodeBITRIX_ERROR DescriptionA Bitrix24 business refusal at the level of the whole batch. The reason is in 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 and above
HTTP429 CodeRATE_LIMITED DescriptionThe request limit is exceeded. The wait time is in the Retry-After header

Full list of common API errors — Errors.

See also