# Catalog product properties

Trade catalog property schema: list, retrieve, create, update, and delete. A property describes the definition of a custom catalog field — `id`, name, and type. It is the companion to [Catalog products](/docs/entities/catalog-products): a product's list-type properties come back there in fields of the form `propertyNNN`, where `NNN` is the property `id`. This entity turns an `id` into a name and type — for example, property `154` → `{ "name": "RU registration name", "propertyType": "S" }`.

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

## Operations

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

## Key fields

| Field | Description |
|------|---------|
| `id` | Property ID. This is the `NNN` in the `propertyNNN` key on a catalog product |
| `iblockId` | Catalog ID. List: [`GET /v1/catalogs`](/docs/entities/catalogs) |
| `name` | The property's display name |
| `propertyType` | Base type. Values: `N` number, `S` string, `L` list, `F` file, `E` element binding, `G` section binding |
| `active` | Whether the property is active |
| `sort` | Sort index |

## What to know before you start

1. **This entity is the catalog property schema.** Each record describes a field definition: `id`, `name`, and `propertyType`. A product's list-type properties come back in [Catalog products](/docs/entities/catalog-products) in fields of the form `propertyNNN`, where `NNN` matches the property `id`. Use the `id` to build a mapping of `id` → name and type, and to label the `propertyNNN` values.
2. **The catalog filter scopes the result to one catalog.** In `GET /v1/catalog-product-properties` and `POST /v1/catalog-product-properties/search` the `filter[iblockId]` field scopes the selection to the properties of one catalog. The `iblockId` value comes from [`GET /v1/catalogs`](/docs/entities/catalogs).
3. **The type code drives the property's behavior.** `propertyType` takes the values `N` number, `S` string, `L` list, `F` file, `E` element binding, `G` section binding.
4. **A minimum of three fields is required to create.** `iblockId`, `name`, and `propertyType` are required. The other fields are optional and take default values.
5. **The type is set on create only.** The `iblockId`, `propertyType`, and `userType` fields are writable on create only. A `PATCH` that includes any of them is rejected with `400 READONLY_FIELD`.
6. **Boolean flags use `true`/`false` values.** `active`, `multiple`, `withDescription`, `searchable`, `filtrable`, `isRequired` are returned and accepted as booleans. Empty strings come back as `null`.

## Typical scenario

1. Find the catalog and its `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Read the catalog property schema: [`GET /v1/catalog-product-properties?filter[iblockId]=19`](./catalog-product-properties/list.md).
3. Build a mapping of `id` → `name` from the returned records.
4. Read a product and resolve its `propertyNNN` fields: [`GET /v1/catalog-products/:id`](/docs/entities/catalog-products).

## 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)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Entity reference](/docs/entities-index)