[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fdeals\u002Fmove":3,"docs-tabs-entities\u002Fdeals\u002Fmove":6},{"content":4,"lastmod":5},"\n## Move deal to another stage\n\n`POST \u002Fv1\u002Fdeals\u002F:id\u002Fmove`\n\nMoves a deal to another stage of its pipeline. The same call can also move the deal to a different pipeline.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Deal ID. List: `GET \u002Fv1\u002Fdeals` |\n\n## Request fields (body)\n\n| Field | Type | Description |\n|------|-----|---------|\n| `stageId` | string | Identifier of the target stage. Stages of the main pipeline — `GET \u002Fv1\u002Fstatuses?filter[entityId]=DEAL_STAGE`, stages of the pipeline whose `categoryId` equals `{N}` — `GET \u002Fv1\u002Fstatuses?filter[entityId]=DEAL_STAGE_{N}` |\n| `categoryId` | number | ID of the target pipeline. Pass it together with a `stageId` from that same pipeline when the deal moves between pipelines. List: `GET \u002Fv1\u002Fdeal-categories` |\n\nFields not listed in the table are ignored.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\u002Fmove\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"stageId\": \"C1:PREPARATION\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\u002Fmove\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"stageId\": \"C1:PREPARATION\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\u002Fmove', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    stageId: 'C1:PREPARATION',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\u002Fmove', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    stageId: 'C1:PREPARATION',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### Moving to another pipeline\n\nThe request body contains a stage of the target pipeline and that pipeline's `categoryId`:\n\n```json\n{\n  \"stageId\": \"C11:NEW\",\n  \"categoryId\": 11\n}\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on a successful call |\n| `data` | object | The deal after the call, all fields — see [Deal fields](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields) |\n| `data.stageId` | string | The stage the deal is on after the call |\n| `data.previousStageId` | string | The stage the deal was on before the call |\n| `data.categoryId` | number | The pipeline the deal belongs to after the call |\n| `data.movedTime` | string | Timestamp of the last stage change, ISO 8601 |\n\n## Response example\n\nThe main fields are shown.\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 741,\n    \"title\": \"Equipment delivery\",\n    \"categoryId\": 1,\n    \"stageId\": \"C1:PREPARATION\",\n    \"previousStageId\": \"C1:NEW\",\n    \"stageSemanticId\": \"P\",\n    \"assignedById\": 1,\n    \"movedBy\": 1,\n    \"movedTime\": \"2026-08-25T10:47:14.000Z\",\n    \"updatedAt\": \"2026-08-25T10:47:14.000Z\"\n  }\n}\n```\n\n## Error response example\n\n404 — no deal with that `id`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Item not found\"\n  }\n}\n```\n\n422 — the stage\u002Fpipeline that was sent was not applied (for example, a `stageId` that is not in the dictionary). By that point Bitrix24 has already accepted the write and the deal has been re-read, so the error response contains the re-read deal in `data`, and `error.details` lists the unapplied fields with their current values:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"STAGE_NOT_APPLIED\",\n    \"message\": \"Bitrix24 accepted the write but did not apply it: stageId requested \\\"C1:BOGUS\\\", still \\\"C1:NEW\\\" after re-read. The value is likely not a valid id for this deal — check GET \u002Fv1\u002Fstatuses?filter[entityId]=... (or GET \u002Fv1\u002Fdeal-categories for a pipeline id) for the valid set before retrying. The record was already written and re-read: any OTHER field in the same request may have been applied, so correct the value and send only what still needs changing rather than repeating the whole body.\",\n    \"details\": {\n      \"unappliedFields\": [\"stageId\"],\n      \"currentValues\": {\n        \"stageId\": \"C1:NEW\"\n      }\n    }\n  },\n  \"data\": {\n    \"id\": 741,\n    \"title\": \"Equipment delivery\",\n    \"categoryId\": 1,\n    \"stageId\": \"C1:NEW\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | No deal with the given `id` |\n| 422 | `STAGE_NOT_APPLIED` | The `stageId`\u002F`categoryId` that was sent was not applied — after the call the value was still the old one (this usually means the stage or pipeline does not exist). Such a call used to return `200` with no warning; now it is an explicit error: details in `error.message` and `error.details`, the re-read deal in `data` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call itself (not the stage value specifically) — a malformed field, for example. The reason is returned in `error.message`, and the machine-readable Bitrix24 code in `error.b24Code` |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the deal |\n| 403 | `SCOPE_DENIED` | The key lacks the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | A key in read-only mode called a write method |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n| 429 | `RATE_LIMITED` | Request limit exceeded. The response includes a `Retry-After` header with the recommended delay |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **An empty body is not an error.** A call with no `stageId`\u002F`categoryId` in the body returns `200`, and the deal stays on its previous stage: there is nothing to compare, so this is not `STAGE_NOT_APPLIED` — the platform only verifies the fields that were actually sent.\n\n## See also\n\n- [Update deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fupdate)\n- [Get deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fget)\n- [Deal fields](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields)\n- [Sales pipelines](\u002Fdocs\u002Fentities\u002Fdeal-categories)\n- [CRM dictionaries](\u002Fdocs\u002Fentities\u002Fstatuses)\n","2026-09-23",{},1794739368595]