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.

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 which aggregation works. 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"
    ]
  }
}

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

Full list of common API errors — Errors.

Known specifics

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