Обновить заказ

PATCH /v1/orders/:id

Обновляет поля существующего заказа. Передавайте только изменяемые поля плоско в корне JSON — без обёртки fields.

Параметры

Параметр Тип Обяз. Описание
id (path) number да Идентификатор заказа

Поля запроса (body)

Поле Тип Описание
statusId string Новый статус заказа. Список: `GET /v1/order-statuses?filter[type]=O`. Усекается до 2 символов без ошибки
discountValue number Значение скидки
canceled boolean Отменён ли заказ
reasonCanceled string Причина отмены
comments string Комментарий менеджера
userDescription string Комментарий покупателя
responsibleId number Ответственный сотрудник
userId number Пользователь Битрикс24 — покупатель. Существование не проверяется
companyId number Идентификатор CRM-компании заказа. Источник: `GET /v1/companies`. Приходит null, если компания не задана
xmlId string Внешний идентификатор

Полный список редактируемых полей — `GET /v1/orders/fields` (поля без флага readonly).

price, marked и reasonMarked на обновлении игнорируются. Запрос вернёт 200, но эти поля не сохранятся — они применяются только при создании. price пересчитывается из позиций корзины: переданная вручную сумма игнорируется, при пустой корзине становится 0. Чтобы изменить сумму, меняйте позиции корзины. payed доступен только для чтения — управляется подсистемой оплат, попытка передать его вернёт 400 READONLY_FIELD.

Примеры

curl — личный ключ

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/orders/845" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statusId": "F",
    "comments": "Закрыт после полной оплаты"
  }'

curl — OAuth-приложение

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/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": "Закрыт после полной оплаты"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/orders/845', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    statusId: 'F',
    comments: 'Закрыт после полной оплаты',
  }),
})

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

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Закрыт после полной оплаты',
  }),
})

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

Поля ответа

Поле Тип Описание
data object Обновлённый объект заказа со всеми полями (см. Поля заказа)

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 845,
    "accountNumber": "443",
    "statusId": "F",
    "price": 100,
    "currency": "RUB",
    "payed": true,
    "canceled": false,
    "comments": "Закрыт после полной оплаты",
    "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
  }
}

Пример ответа при ошибке

422 — заказ не найден:

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

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Заказ с таким ID не найден
400 BITRIX_ERROR Некорректное значение поля — например, неизвестный statusId
400 READONLY_FIELD Передано поле только для чтения — например accountNumber. Номер заказа присваивается автоматически
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Дата dateStatus обновляется автоматически. При изменении statusId поле dateStatus получает текущее время — не передавайте его в запросе.

Поля accountNumber, dateInsert, personTypeXmlId, statusXmlId и другие системные — только для чтения. Попытка передать их на обновлении отклоняется с 400 READONLY_FIELD.

Смотрите также