## Catalog product fields `GET /v1/catalog-products/fields` Returns the product field reference with labels, field types, read/write availability and nullable flags, descriptions and `enum` dictionaries where the value set is fixed, plus the list of fields available for aggregation and the operations available in a batch request. The `dateCreate`, `timestampX`, `dateActiveFrom`, and `dateActiveTo` fields are not accepted in `filter`: the request returns `400 UNKNOWN_FILTER_FIELD` before calling Bitrix24. These dates remain available in `select` and responses. ## Parameters | Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | `iblockId` (query) | number | no | Product catalog ID. List: [`GET /v1/catalogs`](/docs/entities/catalogs). Without the parameter, with an offer catalog ID, or with a nonexistent or non-numeric ID, the response carries the base set of 42 fields and the `fields_partial` warning in `meta.warnings` | ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/catalog-products/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/catalog-products/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { success, data } = await res.json() console.log('Fields:', Object.keys(data.fields).length) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data } = await res.json() ``` ## Response fields `data.fields` is an object whose key matches the field name, and whose value contains the type, the write-access flags, a display label and — for fields with a fixed set of values — their dictionary. The full set of keys is broken down in the table after the field list. `data.aggregatable` lists the fields for `groupBy` in [aggregation](./aggregate.md); numeric functions accept the fields of type `number`. `data.batch` lists the operations available in a [batch request](/docs/batch). Request headers do not switch the language of labels and descriptions. Enum values carry an English `label`. | Field | Type | RO | Description | |------|-----|:--:|---------| | `id` | number | yes | Product identifier | | `name` | string | no | Product name | | `active` | boolean | no | Whether the product is active | | `iblockId` | number | no¹ | Catalog ID. List: [`GET /v1/catalogs`](/docs/entities/catalogs). Set on create only. Changing it via `PATCH` is rejected — a product cannot be moved between catalogs | | `iblockSectionId` | number \| null | no | Catalog section ID. `null` — the product is not linked to a section. List: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) | | `purchasingPrice` | number \| null | no | Purchase price. `null` if not set | | `purchasingCurrency` | string \| null | no | Purchase price currency, for example `USD`. `null` if the purchase price is not set. List: [`GET /v1/currencies`](/docs/entities/currencies) | | `quantity` | number \| null | no | Stock balance. `null` if not set | | `weight` | number \| null | no | Weight of a product unit. `null` if not specified | | `measure` | number | no | Unit of measure ID. List: [`GET /v1/catalog-measures`](/docs/entities/catalog-measures/list) | | `available` | boolean | yes | Whether the product is available for purchase. Computed by Bitrix24 | | `vatIncluded` | boolean | no | VAT included in the price | | `bundle` | boolean | yes | Whether the product is a bundle. Computed by Bitrix24 | | `canBuyZero` | boolean | no | Allow purchase when stock is zero | | `quantityTrace` | boolean | no | Quantity tracking enabled | | `subscribe` | boolean | no | Allow subscription to the product | | `barcodeMulti` | boolean | no | Allow separate barcodes for product units | | `withoutOrder` | boolean | no | Available for ordering without stock on hand | | `dateActiveFrom` | datetime | no | Product activity start date. Not accepted in filters (`400 UNKNOWN_FILTER_FIELD`) | | `dateActiveTo` | datetime | no | Product activity end date. Not accepted in filters (`400 UNKNOWN_FILTER_FIELD`) | | `createdBy` | number | yes | ID of the user who created the product. Filled by the system | | `modifiedBy` | number | yes | ID of the user who modified the product. Filled by the system | | `dateCreate` | datetime | yes | Product creation date. Not accepted in filters (`400 UNKNOWN_FILTER_FIELD`) | | `timestampX` | datetime | yes | Last modification date. Not accepted in filters (`400 UNKNOWN_FILTER_FIELD`) | | `code` | string \| null | no | Product symbolic code. `null` if not set | | `xmlId` | string | no | External identifier | | `sort` | number | no | Sort order | | `vatId` | number | no | Default VAT rate ID. List: [`GET /v1/catalog-vat-rates`](/docs/entities/catalog-vat-rates/list) | | `previewText` | string | no | Preview text | | `detailText` | string | no | Detailed description | | `previewTextType` | string | no | Preview text format: `text` or `html` | | `detailTextType` | string | no | Detailed description format: `text` or `html` | | `previewPicture` | object | no | Preview image | | `detailPicture` | object | no | Detail image | | `iblockSection` | object | no | In the `/fields` reference the type is `object`. Accepts an array of section IDs on create and update. Not returned on read — the primary section is available as the scalar `iblockSectionId`. List: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) | | `width` | number | no | Product width | | `height` | number | no | Product height | | `length` | number | no | Product length | | `quantityReserved` | number \| null | no | Reserved quantity. `null` if there is no reserve | | `recurSchemeLength` | number | no | Payment period length. Available only in on-premise Bitrix24 for content sales | | `recurSchemeType` | string | no | Payment period time unit: `H` — hour, `D` — day, `W` — week, `M` — month, `Q` — quarter, `S` — half-year, `Y` — year. Available only in on-premise Bitrix24 for content sales | | `trialPriceId` | number | no | ID of the product used for a trial payment. Available only in on-premise Bitrix24 for content sales | ¹ `iblockId` is writable on create only (`createOnly`) — in the reference it comes back with `readonly: false` and `createOnly: true`. | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data.fields..type` | string | Field type: `number`, `string`, `boolean`, `datetime`, `object` | | `data.fields..label` | string | Short field label in English | | `data.fields..description` | string | Extended field description: what it is for, where to get the list of allowed values, write-time behavior. The key is present on fields that have something to add to the label | | `data.fields..readonly` | boolean | `true` — the field is filled by the system and is not accepted on create or update | | `data.fields..writeOnly` | boolean | `true` — the field is accepted on write but never returned in responses | | `data.fields..notReturned` | boolean | `true` — the field name is absent from every read response and unsupported in `select` | | `data.fields..createOnly` | boolean | `true` — the field is accepted on create only. On `PATCH` it is rejected with `READONLY_FIELD` (present on `iblockId`) | | `data.fields..nullable` | boolean | `true` — the field can come back as `null`. The key is present only on such fields | | `data.fields..enum` | array | Dictionary of allowed values: an array of `{ value, label }`. The key is present on fields with a fixed set — `previewTextType` and `detailTextType` (`text` and `html`). Send `value` — `label` is meant for display | | `data.aggregatable` | string[] | Fields for `groupBy` in [aggregation](./aggregate.md); numeric functions accept the fields of type `number` | | `data.batch` | string[] | Product operations available in a [batch request](/docs/batch): `create`, `update`, `delete` | | `meta.warnings` | array | Warnings. An element with `code: fields_partial` arrives in a response with the base set of 42 fields — the conditions are listed under the `iblockId` parameter | ## Response example ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "Product identifier" }, "iblockId": { "type": "number", "readonly": false, "createOnly": true, "label": "Catalog ID", "description": "Catalog the product belongs to. Available values: GET /v1/catalogs. Set on create only — changing it via PATCH is rejected, a product cannot be moved between catalogs." }, "purchasingPrice": { "type": "number", "readonly": false, "nullable": true, "label": "Purchase price", "description": "Purchase price of the product; null when not set." }, "iblockSection": { "type": "object", "readonly": false, "writeOnly": true, "notReturned": true, "label": "Catalog sections", "description": "Array of catalog section IDs the product belongs to. Accepted on create and update only — on read the primary section arrives as the scalar iblockSectionId. Available values: GET /v1/catalog-sections." }, "previewTextType": { "type": "string", "readonly": false, "label": "Preview text format", "description": "Format of previewText.", "enum": [ { "value": "text", "label": "Plain text" }, { "value": "html", "label": "HTML" } ] } }, "aggregatable": [ "purchasingPrice", "quantity", "iblockSectionId" ], "batch": [ "create", "update", "delete" ] }, "meta": { "warnings": [ { "code": "fields_partial", "message": "Dynamic field metadata from Bitrix24 was unavailable; the response carries static schema fields only and some labels may be missing. Retry to obtain the complete set." } ] } } ``` The example is trimmed to five fields — one each for `readonly`, `createOnly`, and `nullable`, one carrying the `writeOnly` + `notReturned` pair, and one carrying a machine-readable `enum` dictionary. The response returns all forty-two fields. ## Error response example 403 — no scope: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'catalog' scope" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The API key does not have the `catalog` scope | | 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed | | 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header | For the full list of common API errors, see [Errors](/docs/errors). ## Known specifics **A retry does not clear `fields_partial`.** The warning suggests retrying the request, but a response without `iblockId` is built from the same 42 fields and carries the warning on every call. All 42 fields arrive with labels. **Writing depends on inventory management.** The `quantity`, `purchasingPrice`, and `purchasingCurrency` fields are marked as writable in the reference, but when inventory management is enabled in the Bitrix24 account they are not applied on create or update — stock and purchase prices are managed by inventory documents. **Some fields are not returned in the list by default.** The symbolic code `code`, dimensions `width`, `height`, `length`, texts `previewText`, `detailText`, sort order `sort`, and a number of other fields from the reference are not returned in the `GET /v1/catalog-products` response without an explicit `?select=`. List them in `?select=` to get them in the list — these fields are also available for filtering and sorting. In the single-product response `GET /v1/catalog-products/:id` they are always returned. **Images and section binding are not filterable.** `previewPicture` and `detailPicture` are set on create and update and are returned in responses — in `GET /v1/catalog-products/:id` and in the list via an explicit `?select=` — but they do not support filtering or sorting. The `iblockSection` field accepts an array of section IDs on create and update, but is not returned by `GET /v1/catalog-products/:id` or the list endpoint. The scalar `iblockSectionId`, containing the primary section ID, is available for reading, filtering, and sorting. **The `GET /:id` response contains fields beyond the reference.** A request for a single product additionally returns the product type `type` and custom catalog properties of the form `propertyNNN`. They are not part of the field reference `GET /v1/catalog-products/fields` and are not available for filtering and sorting. In the [list](./list.md) and [search](./search.md) responses, a property is returned when it is named in `select` by its own name. **The product catalog (`iblockId`) is immutable.** The catalog is chosen on create. Bitrix24 does not move a product between catalogs on update. A `PATCH` that changes `iblockId` is rejected with `400 READONLY_FIELD` — previously such a request returned `200` while the product stayed in its original catalog (a false success). **Audit fields are protected.** `createdBy` and `modifiedBy` are filled by Bitrix24 and are not accepted on create or update — passing them is rejected with `400 READONLY_FIELD`. ## See also - [List catalog products](/docs/entities/catalog-products/list) - [Create catalog product](/docs/entities/catalog-products/create) - [Search catalog products](/docs/entities/catalog-products/search) - [Catalog prices](/docs/entities/catalog-prices) - [API reference](/docs/api-reference)