[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fdeals\u002Fupdate":3,"docs-tabs-entities\u002Fdeals\u002Fupdate":6},{"content":4,"lastmod":5},"\n## Update deal\n\n`PATCH \u002Fv1\u002Fdeals\u002F:id`\n\nUpdates the fields of an existing deal. Pass only the fields being changed. For the full list, see the [field reference](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields).\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | yes | Deal ID. List: [`GET \u002Fv1\u002Fdeals`](\u002Fdocs\u002Fentities\u002Fdeals\u002Flist) |\n\n## Frequently updated fields\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `stageId` | string | no | Pipeline stage. Each pipeline has its own set of stages. List: `GET \u002Fv1\u002Fstatuses?filter[entityId]=DEAL_STAGE` for the main pipeline, `DEAL_STAGE_{categoryId}` for the others |\n| `amount` | number | no | Deal amount. To keep a manually set value, pass `isManualOpportunity: true` together with it |\n| `assignedById` | number | no | Assigned person. List: `GET \u002Fv1\u002Fusers` |\n| `title` | string | no | Title |\n| `closedAt` | datetime | no | Closing date |\n| `ufCrm*` | per field schema | no | A user field of the Bitrix24 account, for example `ufCrmProjectCode`. The actual name and type are in the schema [`GET \u002Fv1\u002Fdeals\u002Ffields`](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields), and the value format for each type is in [User fields (UF)](\u002Fdocs\u002Fentity-api#user-fields-uf). An `enumeration` field takes the option `ID` from the field's `items` array in the schema, and a multiple field takes an array of such `ID`s. If you send the option label `VALUE` instead of the `ID`, the value is lost: a single-value field gets `0`. A number that is not among the options is stored as is. Neither the label nor a non-existent `ID` raises an error, and the request returns `200`, so map the label to its `ID` on your side and check the stored value of this field in the response `data` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"stageId\": \"WON\",\n    \"amount\": 75000\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741\" \\\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\": \"WON\",\n    \"amount\": 75000\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F741', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    stageId: 'WON',\n    amount: 75000,\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', {\n  method: 'PATCH',\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: 'WON',\n    amount: 75000,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `data` | object | The updated deal object with all fields — see [Fields](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields) |\n| `meta.warnings` | array | Present when the body carries fields that are neither in the deal schema nor in the field list of [`GET \u002Fv1\u002Fdeals\u002Ffields`](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields), for example a misspelled name. The warning code is `UNRECOGNIZED_WRITE_FIELD`: such a field may not have been stored. The response status is `200`. On a route that wraps the field map itself, an object under `fields` is rejected with `400 NESTED_FIELDS_ENVELOPE` when the schema does not declare `fields`; pass fields flat at the JSON root. |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 741,\n    \"title\": \"Equipment delivery\",\n    \"amount\": 75000,\n    \"currency\": \"USD\",\n    \"stageId\": \"WON\",\n    \"categoryId\": 0,\n    \"assignedById\": 1,\n    \"updatedAt\": \"2026-04-14T09:15:00.000Z\"\n  }\n}\n```\n\n## Error response example\n\n404 — deal not found:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Item not found\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Deal not found |\n| 422 | `STAGE_NOT_APPLIED` | The `stageId`\u002F`categoryId` you sent was not applied: after the `PATCH`, the value is unchanged. A possible cause is that no stage or pipeline with that ID exists. Details are in `error.message` and `error.details`. The re-read deal is in `data`. The record has already been updated, and other fields in the request body may have been applied: correct the value and send only what still needs changing, not the whole body again |\n| 403 | `BITRIX_ACCESS_DENIED` | No access to the deal |\n| 400 | `INVALID_PARAMS` | A field value has the wrong type or format, or the `id` in the path is not a non-negative integer |\n| 400 | `EMPTY_UPDATE_BODY` | The request body is empty: there are no fields to change |\n| 400 | `READONLY_FIELD` | The request body contains a read-only field, such as `isWon`. Such fields are marked in the RO column of [Deal fields](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields) |\n| 403 | `SCOPE_DENIED` | API key lacks the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — see [access rights](\u002Fdocs\u002Faccess-rights) |\n| 401 | `TOKEN_MISSING` | API key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Working with files in CRM fields](\u002Fdocs\u002Frecipes\u002Fcrm-files)\n- [Get deal](\u002Fdocs\u002Fentities\u002Fdeals\u002Fget)\n- [Deal fields](\u002Fdocs\u002Fentities\u002Fdeals\u002Ffields)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","2026-10-15",{},1794739369713]