Обновить позицию корзины

PATCH /v1/basket-items/:id

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

Параметры

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

Поля для обновления (тело)

Параметр Тип Описание
quantity number Количество
price number Цена за единицу
basePrice number Базовая цена до скидки
discountPrice number Размер скидки за единицу
currency string Валюта
name string Переопределение названия товара
vatRate number Ставка НДС в долях единицы
vatIncluded boolean Включён ли НДС в цену
customPrice boolean Защита цены от автопересчёта
weight number Вес в граммах
measureCode number Код единицы измерения
xmlId string Внешний идентификатор

Редактируются все поля позиции, кроме служебных (id, orderId, productId, productXmlId, catalogXmlId, dateInsert, dateUpdate). Полный набор доступных полей виден в ответе `GET /v1/basket-items/:id`.

Частичное обновление. Передавать quantity в каждом запросе не нужно. При отсутствии quantity в теле обёртка дочитывает текущее количество позиции и подставляет его — можно изменить только цену или другое поле. Если при таком частичном обновлении позиция не найдена, вернётся 404 ENTITY_NOT_FOUND.

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/basket-items/9" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "discountPrice": 50
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/basket-items/9" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "discountPrice": 50
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 3,
    discountPrice: 50,
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 3,
    discountPrice: 50,
  }),
})

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

Поля ответа

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

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

JSON 
{
  "success": true,
  "data": {
    "id": 9,
    "orderId": 33,
    "productId": 119,
    "name": "Домашние Тапочки Любимый Спорт",
    "price": 470,
    "basePrice": 470,
    "discountPrice": 50,
    "currency": "RUB",
    "quantity": 3,
    "vatRate": 0,
    "vatIncluded": true,
    "customPrice": false,
    "canBuy": true,
    "weight": 0,
    "measureCode": 796,
    "measureName": "шт",
    "dateUpdate": "2026-05-13T11:58:14.000Z"
  }
}

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

422 — позиция не найдена:

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

Ошибки

HTTP Код Описание
404 ENTITY_NOT_FOUND Позиция не найдена (частичный PATCH без quantity — определяется на предзагрузке)
422 BITRIX_ERROR Позиция с таким ID не найдена (PATCH с явным quantity)
400 BITRIX_ERROR Некорректное значение поля
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Поля id, orderId, productId, productXmlId, catalogXmlId, dateInsert доступны только для чтения. Они проставляются при создании, попытка изменить их игнорируется. Чтобы перенести позицию в другой заказ, удалите её через `DELETE /v1/basket-items/:id` и создайте новую через `POST /v1/basket-items`.

Защита цены через customPrice. При customPrice: true цена позиции не будет пересчитана автоматически при изменении цены товара в каталоге.

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