Recipe: Bulk update deals

Goal

Read a CSV mapping of dealId,newStageId and apply the stage change to every row. Could be hundreds of deals or tens of thousands — BatchByChunkV2.make() chunks the calls into 50-per-batch blocks server-side, no manual paging.

Stack & Prerequisites

Node.js 20+, ESM
@bitrix24/b24jssdk@^1.0.0
A webhook with the crm scope, set as B24_HOOK.

A CSV file migrations.csv:

dealId,newStageId
1234,WON
1235,WON
1240,LOSE

pnpm add @bitrix24/b24jssdk
export B24_HOOK="https://your-portal.bitrix24.com/rest/1/xxxxxxxxxxxxxxxx/"

Full Example

scripts/migrate-deals.mjs:

import { readFile } from 'node:fs/promises'
import {
  B24Hook,
  EnumCrmEntityTypeId,
  ParamsFactory
} from '@bitrix24/b24jssdk'

const hookUrl = process.env.B24_HOOK
if (!hookUrl) {
  console.error('B24_HOOK is not set')
  process.exit(2)
}

const csv = await readFile(process.argv[2] ?? 'migrations.csv', 'utf8')
const rows = csv
  .split(/\r?\n/)
  .slice(1) // header
  .filter(Boolean)
  .map((line) => {
    const [dealId, newStageId] = line.split(',')
    return { dealId: Number(dealId), newStageId }
  })

console.log(`planned updates: ${rows.length}`)

const b24 = B24Hook.fromWebhookUrl(hookUrl, {
  restrictionParams: ParamsFactory.getBatchProcessing()
})

const calls = rows.map(({ dealId, newStageId }) => [
  'crm.item.update',
  {
    entityTypeId: EnumCrmEntityTypeId.deal,
    id: dealId,
    fields: { stageId: newStageId }
  }
])

const response = await b24.actions.v2.batchByChunk.make({
  calls,
  options: {
    isHaltOnError: false,
    requestId: `deal-stage-migration-${Date.now()}`
  }
})

if (!response.isSuccess) {
  console.error('partial failure:')
  for (const message of response.getErrorMessages()) {
    console.error(`  - ${message}`)
  }
  process.exit(1)
}

console.log(`updated: ${response.getData()?.length ?? 0} of ${rows.length}`)

Run It

node scripts/migrate-deals.mjs migrations.csv
# planned updates: 3450
# updated: 3450 of 3450

If a few rows fail (deleted deal, missing scope, invalid stage), isHaltOnError: false lets the rest of the batch finish and the script exits with code 1 after listing the failures.

How It Works

BatchByChunkV2.make({ calls }) accepts an arbitrary number of commands and slices them internally into batches of 50, the per-request hard limit. Output order matches input order.
Result.isSuccess flips to false if any chunk had an error. getErrorMessages() returns one message per failed call. Successful calls are still in getData() — partial progress is preserved.
ParamsFactory.getBatchProcessing() makes the client more cautious, not more permissive: it halves the request rate (drainRate 2 → 1, burstLimit 50 → 30) and lowers the thresholds at which it warns and starts adding delay (both 80% → 50%), so a long migration backs off earlier and keeps the portal queue responsive for live UI traffic. The operating budget itself is unchanged.
Naming the request via options.requestId makes it easy to filter portal-side logs. It does not deduplicate an accidental re-run — it is a tracking tag, and the portal happily writes twice. On restApi:v3 an idempotencyKey is what prevents that.

Limitations

The two-tuple calls form is required: BatchByChunkV2 deliberately rejects named-object commands because chunk boundaries would split the names apart.
Each command counts against the daily method-call budget. For tens of thousands of updates, schedule the script to run during off-peak hours and consider splitting by responsible user.
Bitrix24's crm.item.update validates stageId against the deal's category. A typo in newStageId returns a per-call error — visible in getErrorMessages() — but the whole script does not abort thanks to isHaltOnError: false.
Atomic rollback is not supported. If you need transactional behavior, dump current values into a separate CSV first and run a second migration to restore.