# Цены каталога

Цены товаров: список, получение, создание, изменение и удаление. У одного товара может быть несколько цен — по одной на каждый тип цены (`catalogGroupId`). Цены привязаны к товарам из [каталога](/docs/entities/catalog-products).

Битрикс24 API: `catalog.price.*`
Скоуп: `catalog`

## Операции

- [Создать цену](./catalog-prices/create.md) — `POST /v1/catalog-prices`
- [Список цен](./catalog-prices/list.md) — `GET /v1/catalog-prices`
- [Получить цену](./catalog-prices/get.md) — `GET /v1/catalog-prices/:id`
- [Обновить цену](./catalog-prices/update.md) — `PATCH /v1/catalog-prices/:id`
- [Удалить цену](./catalog-prices/delete.md) — `DELETE /v1/catalog-prices/:id`
- [Поиск цен](./catalog-prices/search.md) — `POST /v1/catalog-prices/search`
- [Поля цены](./catalog-prices/fields.md) — `GET /v1/catalog-prices/fields`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `productId` | ID товара, к которому относится цена. Список: [`GET /v1/catalog-products?filter[iblockId]=21`](/docs/entities/catalog-products) |
| `catalogGroupId` | Тип цены. Базовая цена — `1`. Какие типы заведены на портале, видно по значениям `catalogGroupId` в [списке цен](./catalog-prices/list.md) |
| `price` | Значение цены |
| `currency` | Валюта цены, например `RUB`. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `quantityFrom` | Нижняя граница количественного диапазона, если цена зависит от количества |
| `quantityTo` | Верхняя граница количественного диапазона |

## Что нужно знать перед работой

1. **Минимум для создания — четыре поля.** `productId`, `catalogGroupId`, `price`, `currency` обязательны; без любого из них запрос вернёт ошибку. `quantityFrom` и `quantityTo` опциональны.
2. **Тип цены задаётся числом `catalogGroupId`.** Базовая цена соответствует `1`. Отдельного эндпоинта со списком типов цен нет — доступные на портале значения видно по полю `catalogGroupId` в [списке цен](./catalog-prices/list.md). Один товар может иметь по одной цене на каждый тип.
3. **Цена привязана к товару.** Перед созданием получите `productId` из [`GET /v1/catalog-products`](/docs/entities/catalog-products) (товарам нужен фильтр `filter[iblockId]`, а `iblockId` — из [`GET /v1/catalogs`](/docs/entities/catalogs)).
4. **В ответе больше полей, чем доступно для фильтра.** Кроме перечисленных, в ответе приходят `extraId`, `priceScale` (цена в базовой валюте) и `timestampX` (дата изменения). Фильтрация и сортировка работают только по полям из таблицы выше.

## Типичный сценарий

1. Найти каталог и его `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Найти товар: [`GET /v1/catalog-products?filter[iblockId]=21`](/docs/entities/catalog-products) — взять `id` товара.
3. Посмотреть текущие цены товара: [`GET /v1/catalog-prices?filter[productId]=101`](./catalog-prices/list.md).
4. Создать или изменить цену: [`POST /v1/catalog-prices`](./catalog-prices/create.md) / [`PATCH /v1/catalog-prices/:id`](./catalog-prices/update.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Товары каталога](/docs/entities/catalog-products)
- [Каталоги](/docs/entities/catalogs)
- [Разделы каталога](/docs/entities/catalog-sections)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)