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.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionDeal ID. List: GET /v1/deals

Frequently updated fields

Parameter Type Required Description
ParameterstageId Typestring Requiredno DescriptionPipeline stage. Each pipeline has its own set of stages. List: GET /v1/statuses?filter[entityId]=DEAL_STAGE for the main pipeline, DEAL_STAGE_{categoryId} for the others
Parameteramount Typenumber Requiredno DescriptionDeal amount. To keep a manually set value, pass isManualOpportunity: true together with it
ParameterassignedById Typenumber Requiredno DescriptionAssigned person. List: GET /v1/users
Parametertitle Typestring Requiredno DescriptionTitle
ParameterclosedAt Typedatetime Requiredno DescriptionClosing date
ParameterufCrm* Typeper field schema Requiredno DescriptionA 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
Fielddata Typeobject DescriptionThe updated deal object with all fields — see Fields
Fieldmeta.warnings Typearray DescriptionPresent when the body carries fields that are neither in the deal schema nor in the field list of GET /v1/deals/fields, 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.

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
HTTP404 CodeENTITY_NOT_FOUND DescriptionDeal not found
HTTP422 CodeSTAGE_NOT_APPLIED DescriptionThe stageId/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
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo access to the deal
HTTP400 CodeINVALID_PARAMS DescriptionA field value has the wrong type or format, or the id in the path is not a non-negative integer
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty: there are no fields to change
HTTP400 CodeREADONLY_FIELD DescriptionThe request body contains a read-only field, such as isWon. Such fields are marked in the RO column of Deal fields
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

See also