# Catalog prices

Product prices: list, retrieve, create, update and delete. A single product can have several prices — one per price type (`catalogGroupId`). Prices are linked to products from the [catalog](/docs/entities/catalog-products).

Bitrix24 API: `catalog.price.*`
Scope: `catalog`

## Operations

- [Create a price](./catalog-prices/create.md) — `POST /v1/catalog-prices`
- [List prices](./catalog-prices/list.md) — `GET /v1/catalog-prices`
- [Get a price](./catalog-prices/get.md) — `GET /v1/catalog-prices/:id`
- [Update a price](./catalog-prices/update.md) — `PATCH /v1/catalog-prices/:id`
- [Delete a price](./catalog-prices/delete.md) — `DELETE /v1/catalog-prices/:id`
- [Search prices](./catalog-prices/search.md) — `POST /v1/catalog-prices/search`
- [Price fields](./catalog-prices/fields.md) — `GET /v1/catalog-prices/fields`

## Key fields

| Field | Description |
|------|---------|
| `productId` | ID of the product the price belongs to. List: [`GET /v1/catalog-products?filter[iblockId]=21`](/docs/entities/catalog-products) |
| `catalogGroupId` | Price type. Base price is `1`. The types configured in your Bitrix24 account are visible from the `catalogGroupId` values in the [price list](./catalog-prices/list.md) |
| `price` | Price value |
| `currency` | Price currency, e.g. `USD`. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `quantityFrom` | Lower bound of the quantity range, if the price depends on quantity |
| `quantityTo` | Upper bound of the quantity range |

## What to know before you start

1. **The minimum to create is four fields.** `productId`, `catalogGroupId`, `price`, `currency` are required; without any of them the request returns an error. `quantityFrom` and `quantityTo` are optional.
2. **The price type is set by the number `catalogGroupId`.** The base price corresponds to `1`. There is no separate endpoint listing price types — the values available in your Bitrix24 account are visible from the `catalogGroupId` field in the [price list](./catalog-prices/list.md). A single product can have one price per type.
3. **A price is linked to a product.** Before creating, get the `productId` from [`GET /v1/catalog-products`](/docs/entities/catalog-products) (products require the `filter[iblockId]` filter, and `iblockId` comes from [`GET /v1/catalogs`](/docs/entities/catalogs)).
4. **The response has more fields than are available for filtering.** Besides those listed, the response includes `extraId`, `priceScale` (price in the base currency) and `timestampX` (modification date). Filtering and sorting work only on the fields from the table above.

## Typical scenario

1. Find the catalog and its `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Find the product: [`GET /v1/catalog-products?filter[iblockId]=21`](/docs/entities/catalog-products) — take the product `id`.
3. View the product's current prices: [`GET /v1/catalog-prices?filter[productId]=101`](./catalog-prices/list.md).
4. Create or update a price: [`POST /v1/catalog-prices`](./catalog-prices/create.md) / [`PATCH /v1/catalog-prices/:id`](./catalog-prices/update.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Catalog products](/docs/entities/catalog-products)
- [Catalogs](/docs/entities/catalogs)
- [Catalog sections](/docs/entities/catalog-sections)
- [Filtering syntax](/docs/filtering)
- [Entities reference](/docs/entities-index)