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

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/catalog-products/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

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

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; numeric functions accept the fields of type number. data.batch lists the operations available in a batch request.

Request headers do not switch the language of labels and descriptions. Enum values carry an English label.

¹ iblockId is writable on create only (createOnly) — in the reference it comes back with readonly: false and createOnly: true.

Response example

{
  "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:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope"
  }
}

Errors

For the full list of common API errors, see 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 and search 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
• Create catalog product
• Search catalog products
• Catalog prices
• API reference