For AI agents: markdown of this page — /docs-content-en/entities/crm-v3-dictionaries/stages-replace.md documentation index — /llms.txt

Replace funnel stages

PUT /v1/deal-categories/:categoryId/stages

PUT /v1/categories/:entityTypeId/:categoryId/stages

Replaces the editable stage set of a deal or smart-process funnel. Array order determines stage order.

This method requires a CRM update after 26.2200.0; no released version number is available yet. It is not available on all Bitrix24 accounts. An administrator must enable the feature.

Warning: stages omitted from the replacement may be deleted. Use a READWRITE key with the crm scope and permission to manage the funnel stages.

Parameters

Parameter Type Required Default Description
ParametercategoryId (path) Typenumber Requiredyes Default— DescriptionNonnegative safe integer. 0 is the main deal funnel. Get an ID from Deal funnels or Funnels
ParameterentityTypeId (path) Typenumber Requiredyes, alternate path Default— Description2 for deals, or a dynamic type from Smart processes. Other fixed CRM types are rejected

Request body

Field Type Required Description
Fieldstages Typearray Requiredyes DescriptionOrdered replacement set, at most 50 entries. An empty array removes removable stages, subject to permission and usage checks
Fieldstages[].stageId Typestring | null Requiredno DescriptionExisting full stage ID from the statusId field in Statuses or a previous replacement response. Omit or pass null to create a stage
Fieldstages[].name Typestring Requiredyes DescriptionStage name, up to 100 characters
Fieldstages[].color Typestring Requiredno Description#RRGGBB or an empty string to clear the color. Omission preserves the existing color
Fieldstages[].description Typestring Requiredno DescriptionStage description

Examples

Replace 29 with your own test funnel ID.

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/deal-categories/29/stages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stages":[{"name":"VIBE-PROBE First"},{"name":"VIBE-PROBE Second"}]}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/deal-categories/29/stages" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stages":[{"name":"VIBE-PROBE First"},{"name":"VIBE-PROBE Second"}]}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deal-categories/29/stages', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"stages":[{"name":"VIBE-PROBE First"},{"name":"VIBE-PROBE Second"}]}),
})
const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deal-categories/29/stages', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"stages":[{"name":"VIBE-PROBE First"},{"name":"VIBE-PROBE Second"}]}),
})
const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionFunnel stages after replacement
Fielddata[].stageId Typestring DescriptionFull stage ID from this response or the statusId field in Statuses
Fielddata[].categoryId Typenumber DescriptionFunnel ID from Deal funnels
Fielddata[].name Typestring DescriptionStage name
Fielddata[].sort Typenumber DescriptionSort order
Fielddata[].semantics Typestring Descriptionprocess, success or failure
Fielddata[].color Typestring DescriptionColor or an empty string
Fielddata[].isSystem Typeboolean DescriptionWhether the stage is a system stage
Fielddata[].description Typestring DescriptionStage description

Response example

HTTP 200.

JSON 
{
  "success": true,
  "data": [
    {
      "stageId": "C29:NEW",
      "categoryId": 29,
      "name": "New",
      "sort": 10,
      "semantics": "process",
      "color": "#1F86FF",
      "isSystem": true,
      "description": ""
    },
    {
      "stageId": "C29:UC_975XX9",
      "categoryId": 29,
      "name": "VIBE-PROBE First",
      "sort": 20,
      "semantics": "process",
      "color": "",
      "isSystem": false,
      "description": ""
    },
    {
      "stageId": "C29:UC_8U03YB",
      "categoryId": 29,
      "name": "VIBE-PROBE Second",
      "sort": 30,
      "semantics": "process",
      "color": "",
      "isSystem": false,
      "description": ""
    },
    {
      "stageId": "C29:WON",
      "categoryId": 29,
      "name": "Deal won",
      "sort": 40,
      "semantics": "success",
      "color": "#7BD500",
      "isSystem": true,
      "description": ""
    },
    {
      "stageId": "C29:LOSE",
      "categoryId": 29,
      "name": "Deal lost",
      "sort": 50,
      "semantics": "failure",
      "color": "#FF5752",
      "isSystem": true,
      "description": ""
    },
    {
      "stageId": "C29:APOLOGY",
      "categoryId": 29,
      "name": "Failure analysis",
      "sort": 60,
      "semantics": "failure",
      "color": "#FF5752",
      "isSystem": false,
      "description": ""
    }
  ]
}

Error response example

400 — malformed replacement body:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use a nonnegative categoryId and a stages array with name and optional stageId, color and description"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid path or request body
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown or repeated query parameter
HTTP404 CodeENTITY_NOT_FOUND DescriptionFunnel or stage not found
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionInsufficient Bitrix24 permissions
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA READONLY key cannot write
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 credentials
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe feature is disabled or the method is unavailable on this portal. error.release identifies the update
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned a malformed response

Other native Bitrix24 refusals retain their HTTP status, code and message, with credentials removed. For common API errors, see Errors.

Known specifics

System and final stages are preserved even when omitted. Attempts to modify them or delete a stage used by records are rejected. The set is replaced transactionally, without migrating records.

Do not blindly retry after a timeout or connection failure: replacement may have completed, and entries without stageId request new stages. Read the current stages before deciding whether to submit again.

See also