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

Update deal

PATCH /v1/deals/:id

Updates the fields of an existing deal. Pass only the fields being changed. For the full list, see the field reference.

Frequently updated fields

Parameter Type Description
stageId string Pipeline stage. List: GET /v1/statuses?filter[entityId]=DEAL_STAGE
amount number Deal amount
assignedById number Assigned person. List: GET /v1/users
title string Title
closedAt datetime Closing date
ufCrm* per field schema A user field of the Bitrix24 account, for example ufCrmProjectCode. The actual name and type are in the schema GET /v1/deals/fields, and the value format for each type is in 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 IDs. 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

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/deals/741" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "WON",
    "amount": 75000
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/deals/741" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "WON",
    "amount": 75000
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/741', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'WON',
    amount: 75000,
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals/741', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stageId: 'WON',
    amount: 75000,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
data object The updated deal object with all fields — see Fields

The updated deal object with all fields — see Deal fields.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 741,
    "title": "Equipment delivery",
    "amount": 75000,
    "currency": "USD",
    "stageId": "WON",
    "categoryId": 0,
    "assignedById": 1,
    "updatedAt": "2026-04-14T09:15:00.000Z"
  }
}

Error response example

404 — deal not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND Deal not found
422 STAGE_NOT_APPLIED The stageId/categoryId that was sent was not applied — after the PATCH the value remained unchanged (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. 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
403 ACCESS_DENIED No access to the deal
400 INVALID_REQUEST Invalid fields
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
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

See also