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

Update an order

PATCH /v1/orders/:id

Updates the fields of an existing order. Pass only the fields being changed, flat at the root of the JSON — no fields wrapper.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionOrder identifier

Request fields (body)

Field Type Description
FieldstatusId Typestring DescriptionNew order status. List: GET /v1/order-statuses?filter[type]=O. Truncated to 2 characters without an error
FielddiscountValue Typenumber DescriptionDiscount value
Fieldcanceled Typeboolean DescriptionWhether the order is canceled
FieldreasonCanceled Typestring DescriptionCancellation reason
Fieldcomments Typestring DescriptionManager's comment
FielduserDescription Typestring DescriptionBuyer's comment
FieldresponsibleId Typenumber DescriptionResponsible employee
FielduserId Typenumber DescriptionBitrix24 user — the buyer. Existence is not checked
FieldcompanyId Typenumber DescriptionIdentifier of the order's CRM company. Source: GET /v1/companies. Returned as null if no company is set
FieldxmlId Typestring DescriptionExternal identifier

Full list of editable fields — GET /v1/orders/fields (fields without the readonly flag).

price, marked, and reasonMarked are rejected on update with 400 READONLY_FIELD. Only creation accepts them: the Bitrix24 update method does not save these fields. Previously the request returned 200 and the value was silently lost — for price that meant losing data, because the amount is recalculated from the basket items and becomes 0 when the basket is empty. To change the amount after creation, edit the basket items. payed is read-only on creation as well — it is managed by the payments subsystem.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/orders/845" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statusId": "F",
    "comments": "Closed after full payment"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/orders/845" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statusId": "F",
    "comments": "Closed after full payment"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/orders/845', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    statusId: 'F',
    comments: 'Closed after full payment',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/orders/845', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    statusId: 'F',
    comments: 'Closed after full payment',
  }),
})

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

Response fields

Field Type Description
Fielddata Typeobject DescriptionThe updated order object with all fields (see Order fields)

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 845,
    "accountNumber": "443",
    "statusId": "F",
    "price": 100,
    "currency": "USD",
    "payed": true,
    "canceled": false,
    "comments": "Closed after full payment",
    "dateInsert": "2026-04-21T06:48:16.000Z",
    "dateUpdate": "2026-05-13T11:45:32.000Z",
    "dateStatus": "2026-05-13T11:45:32.000Z",
    "userId": 1,
    "companyId": 15,
    "clients": [
      { "entityTypeId": 3, "entityId": 2471, "isPrimary": true, "roleId": 0, "sort": 0 },
      { "entityTypeId": 4, "entityId": 15, "isPrimary": true, "roleId": 0, "sort": 0 }
    ],
    "responsibleId": 1
  }
}

Error response example

422 — order not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "order is not exists"
  }
}

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR DescriptionAn order with this ID was not found
HTTP400 CodeBITRIX_ERROR DescriptionInvalid field value — for example, an unknown statusId
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was passed — for example, accountNumber. The order number is assigned automatically. This also covers price, marked, and reasonMarked: they are accepted only on creation
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The dateStatus field is updated automatically. When statusId changes, dateStatus receives the current time — do not pass it in the request.

The accountNumber, dateInsert, personTypeXmlId, statusXmlId, and other system fields are read-only. Passing them on update is rejected with 400 READONLY_FIELD.

See also