Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-offers/update.md индекс документации — /llms.txt

Изменить вариацию

PATCH /v1/catalog-offers/:id

Изменяет существующую вариацию товара. Поля передаются плоско в корне JSON, передавайте только изменяемые — остальные сохраняют текущие значения.

Параметры

Параметр Тип Обяз. Описание
id (path) number да Идентификатор вариации. Список: GET /v1/catalog-offers

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

Основные изменяемые поля — name, active, purchasingPrice, quantity.

Поле Тип Обяз. Описание
name string нет Название вариации
active boolean нет Активна ли вариация
iblockSectionId number нет ID раздела каталога. Список: GET /v1/catalog-sections
measure number нет ID единицы измерения. Список: GET /v1/catalog-measures
weight number нет Вес единицы товара
vatIncluded boolean нет НДС включён в цену
canBuyZero boolean нет Разрешить покупку при нулевом остатке
quantityTrace boolean нет Включить учёт количества
subscribe boolean нет Разрешить подписку на товар
barcodeMulti boolean нет Отдельные штрихкоды для единиц товара
withoutOrder boolean нет Доступна к заказу без наличия на складе
purchasingPrice number нет Закупочная цена
purchasingCurrency string нет Валюта закупочной цены. Список: GET /v1/currencies
quantity number нет Остаток на складе
quantityReserved number нет Зарезервированное количество
code string нет Символьный код
xmlId string нет Внешний код
sort number нет Порядок сортировки
vatId number нет ID ставки НДС. Список: GET /v1/catalog-vat-rates
height number нет Высота
length number нет Длина
width number нет Ширина
dateActiveFrom datetime нет Начало активности
dateActiveTo datetime нет Конец активности
previewText string нет Текст анонса
detailText string нет Подробное описание
previewTextType string нет Формат текста анонса: text или html
detailTextType string нет Формат подробного описания: text или html
previewPicture object нет Картинка анонса
detailPicture object нет Детальная картинка
iblockSection object нет Массив ID разделов каталога, к которым относится вариация. Список: GET /v1/catalog-sections
recurSchemeLength number нет Длина периода оплаты. Только для коробочной версии Битрикс24 при продаже контента
recurSchemeType string нет Единица периода оплаты: H, D, W, M, Q, S, Y. Только для коробочной версии Битрикс24 при продаже контента
trialPriceId number нет ID товара пробной оплаты. Только для коробочной версии Битрикс24 при продаже контента
propertyNNN object/array нет Значение свойства каталога объектом { "value": … }, где NNN — ID свойства. Свойства каталога — в GET /v1/catalog-offers/fields?iblockId=<id>

Тело должно содержать хотя бы одно записываемое поле. Пустой PATCH отклоняется с 400 EMPTY_UPDATE_BODY, тело только из неизвестных имён — с 400 NO_RECOGNIZED_UPDATE_FIELDS.

Поля parentId, iblockId и type при изменении не принимаются: связь с головным товаром и каталог задаются при создании, тип вычисляет Битрикс24. Поля с readonly: true в Полях вариации, например available, заполняются системой. Любое из этих полей в теле отклоняется с 400 READONLY_FIELD.

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/catalog-offers/7191" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "purchasingPrice": 470
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/catalog-offers/7191" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purchasingPrice": 470
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-offers/7191', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    purchasingPrice: 470,
  }),
})

const { success, data } = await res.json()
console.log('Закупочная цена:', data.purchasingPrice)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-offers/7191', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    purchasingPrice: 470,
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Полный объект изменённой вариации. Набор полей — как у GET /v1/catalog-offers/:id

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

Показаны основные поля.

JSON 
{
  "success": true,
  "data": {
    "id": 7191,
    "iblockId": 27,
    "name": "Футболка базовая, размер M",
    "parentId": { "value": "7189", "valueId": "3895" },
    "type": 4,
    "active": true,
    "available": true,
    "measure": 9,
    "purchasingPrice": 470,
    "purchasingCurrency": "RUB",
    "quantity": null,
    "dateCreate": "2026-10-08T18:41:55.000Z",
    "timestampX": "2026-10-08T18:41:59.000Z"
  }
}

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

404 — вариации с указанным id нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "offer does not exist."
  }
}

Ошибки

HTTP Код Описание
404 ENTITY_NOT_FOUND Записи с указанным id нет (offer does not exist.)
422 BITRIX_ERROR id принадлежит обычному товару, а не вариации (productType is not allowed for this catalog)
400 EMPTY_UPDATE_BODY Тело запроса пустое — передайте хотя бы одно поле
400 NO_RECOGNIZED_UPDATE_FIELDS В теле нет ни одного распознанного записываемого поля. Сообщение перечисляет допустимые
400 READONLY_FIELD В теле передано поле, которое при изменении не принимается: parentId, iblockId, type или поле только для чтения, например available
403 SCOPE_DENIED Ключу не хватает скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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

Свойство каталога передаётся объектом. PATCH со скалярным значением свойства — "property891": "B-200" — отвечает 200, но значение не записывает, а очищает. Так ведут себя строковое и списочное свойства. Передавайте { "value": … }, для списочного свойства — ID варианта строкой: { "value": "1601" }. ID вариантов — в GET /v1/catalog-product-property-enums с filter[propertyId]. При создании вариации свойство принимает и простое значение.

Вариацию нельзя перенести к другому головному товару. parentId задаётся только при создании. Чтобы привязать вариацию к другому головному товару, создайте её заново с нужным parentId и удалите прежнюю.

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