# Catalog list-property values

Dictionary of the options of a trade-catalog list property: read the list, get a single element, search, and inspect the field reference. Each record is one option of a dropdown — the element `id` and its readable text `value`. It is the companion to [Catalog product properties](/docs/entities/catalog-product-properties): a property with `propertyType: "L"` describes the field, and this entity enumerates the options that can be selected in it.

This is the source of what no product endpoint provides: **all possible** values of a list property, not just the one selected on a particular product.

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

## Operations

- [List values](./catalog-product-property-enums/list.md) — `GET /v1/catalog-product-property-enums`
- [Get a value](./catalog-product-property-enums/get.md) — `GET /v1/catalog-product-property-enums/:id`
- [Search values](./catalog-product-property-enums/search.md) — `POST /v1/catalog-product-property-enums/search`
- [Value fields](./catalog-product-property-enums/fields.md) — `GET /v1/catalog-product-property-enums/fields`

The entity is read-only: `POST`, `PATCH`, `DELETE`, and `POST /aggregate` are not registered and answer `404`.

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Identifier of the enumeration element. This is the value a catalog product carries in `propertyNNN.value` |
| `propertyId` | number | Identifier of the owning property. Required in the filter |
| `value` | string | Readable text of the option — the same text a product returns in `propertyNNN.valueEnum` |
| `def` | boolean | Whether this option is the property's default value |
| `sort` | number | Sort index within the property |
| `xmlId` | string | External code. Comes back as `null` when not set |

## What to know before you start

1. **`filter[propertyId]` is required.** The dictionary is read one property at a time. A request without this filter is rejected with `400 MISSING_REQUIRED_FILTER` before Bitrix24 is called — on both available surfaces: the list and [search](./catalog-product-property-enums/search.md). Take `propertyId` from [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties). The check looks at the **presence** of the key, not at the shape of its value, and does not extend to the sub-calls of a [batch request](/docs/batch) — it is a cost guard and a hint, not an access boundary: whatever a key with the `catalog` scope can reach, it can reach without this filter too.
2. **Only `propertyType: "L"` has an enumeration.** Read the property type first: [`GET /v1/catalog-product-properties/:id`](/docs/entities/catalog-product-properties/get). For a property of any other type (`S` string, `N` number, `F` file, `E`/`G` bindings) the request returns an **empty list**, not an error.
3. **The link to product fields goes through `id`.** A catalog product returns a list-property value in the field `propertyNNN`, where `NNN` is the property `id`. Inside are `value` (the enumeration element id, as a string), `valueEnum` (the ready-made readable text), and `valueId` (the value row id). Match with `String(element.id) === product.propertyNNN.value` — the product's `value` is a string while the dictionary `id` is a number.
4. **The shape on the product side depends on the property's `listType`.** With `listType: "L"` (dropdown) an object with the three fields above arrives. With `listType: "C"` (checkbox) a bare `"Y"`/`"N"` scalar arrives — that is the state of the checkbox, not an option identifier. Such a property still has a dictionary, and it returns a single record carrying the label of the checked state. It cannot be joined to the product by `id`: the product carries a flag, not an element id. When `multiple: true`, the same shape arrives as an array — expand every element.
5. **Pagination is ordinary: `limit` + `offset`, end of data by `meta.hasMore`.** Bitrix24 reports the total, so `meta.total` and `meta.hasMore` are trustworthy. The ceiling is 5000 records per call, the default is 50. Rare edge case: if no total arrives, the platform substitutes the length of the received window into `meta.total`, so `hasMore` comes back `false` on a full page — compare `data.length` against the page size to be safe.
6. **Every field is read-only.** List options are created in the Bitrix24 interface. `GET /v1/catalog-product-property-enums/fields` returns `batch: []` — the entity has no write operations.

## Typical scenario

The task: show the user a dropdown with **all** sizes and highlight the one selected on a product.

1. Find the catalog `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs). Done once and cached.
2. Read the catalog property schema: [`GET /v1/catalog-product-properties?filter[iblockId]=26`](/docs/entities/catalog-product-properties/list). Three property fields matter here — `propertyType` (only `L` has an enumeration), `listType` (an object or a bare scalar on the product), and `multiple` (a single object or an array). Cached together with step 1.
3. Fetch the option dictionary: [`GET /v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000`](./catalog-product-property-enums/list.md). Build a `String(id) → value` map.
4. Read the product: [`GET /v1/catalog-products/160`](/docs/entities/catalog-products/get) — `property166.value` carries `"116"`, and the map expands it into `L`.

For a single product step 3 is unnecessary: the text is already in `property166.valueEnum`. The dictionary is needed exactly when **all** options are required — a dropdown, a filter, an export.

Dictionaries for several properties are fetched at once with one [batch request](/docs/batch) — up to 50 sub-calls, one per `propertyId`. A sample body is in the "Known specifics" section of the [list values](./catalog-product-property-enums/list.md) page. Data cannot be passed between the sub-calls of one batch: that is why step 2 stays a separate cached call, while the batch saves N dictionary round-trips for **already known** `propertyId` values.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Default `limit` | 50 |
| Auto-pagination | kicks in at `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 product properties](/docs/entities/catalog-product-properties)
- [Catalog products](/docs/entities/catalog-products)
- [Catalogs](/docs/entities/catalogs)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Entity reference](/docs/entities-index)