# Catalog prices

Product prices: list, retrieve, create, update and delete. A single product can have several prices: prices of different types and, within one type, prices for different quantity ranges. 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. Type numbers depend on the account: get the list from [`GET /v1/catalog-price-types`](/docs/entities/catalog-price-types); the base type is the record with `base: "Y"` |
| `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 a price 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 numeric `catalogGroupId`, and that number depends on the account.** Do not assume `1` is the base price: numbers are assigned as types are created, so on different accounts the base type is 1, 3 or 7. Fetch the list [`GET /v1/catalog-price-types`](/docs/entities/catalog-price-types) and identify the base type as the record whose `base` equals `Y` — there is exactly one such record. Without quantity ranges, a product can have only one price of each type.
3. **A price is linked to a product.** Before creating a price, 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 a write accepts.** Besides those listed, the response includes `extraId`, `priceScale` (price in the base currency) and `timestampX` (modification date). They are set by the system, but you can filter and sort by them.

## 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. Look up the number of the price type you need: [`GET /v1/catalog-price-types`](/docs/entities/catalog-price-types) — for the base price take the `id` of the record with `base: "Y"`.
4. View the product's current prices: [`GET /v1/catalog-prices?filter[productId]=101`](./catalog-prices/list.md).
5. 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 price types](/docs/entities/catalog-price-types)
- [Catalog products](/docs/entities/catalog-products)
- [Catalogs](/docs/entities/catalogs)
- [Catalog sections](/docs/entities/catalog-sections)
- [Filtering syntax](/docs/filtering)
- [API reference](/docs/api-reference)