For AI agents: markdown of this page — /docs-content-en/entities/catalog-products/fields.md documentation index — /llms.txt

Product fields

GET /v1/catalog-products/fields

Returns the product field reference with field types, read-only and nullable flags, the list of fields available for aggregation, and the operations available in a batch request.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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 type (the field type), readonly (true — the field cannot be passed on create or update) and nullable (present when the field can come back as null). data.aggregatable lists the fields for which aggregation works. data.batch lists the operations available in a batch request.

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. 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
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
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
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
dateActiveTo datetime no Product activity end date
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
timestampX datetime yes Last modification date
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
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
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.<name>.type string Field type: number, string, boolean, datetime, object
data.fields.<name>.readonly boolean true — the field is filled by the system and is not accepted on create or update
data.fields.<name>.createOnly boolean true — the field is accepted on create only; on PATCH it is rejected with READONLY_FIELD (present on iblockId)
data.fields.<name>.nullable boolean true — the field can come back as null. The key is present only on such fields
data.aggregatable string[] Fields for which aggregation works
data.batch string[] Product operations available in a batch request: create, update, delete

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "name": { "type": "string", "readonly": false },
      "active": { "type": "boolean", "readonly": false },
      "iblockId": { "type": "number", "readonly": false, "createOnly": true },
      "iblockSectionId": { "type": "number", "readonly": false, "nullable": true },
      "purchasingPrice": { "type": "number", "readonly": false, "nullable": true },
      "purchasingCurrency": { "type": "string", "readonly": false, "nullable": true },
      "quantity": { "type": "number", "readonly": false, "nullable": true },
      "weight": { "type": "number", "readonly": false, "nullable": true },
      "measure": { "type": "number", "readonly": false },
      "available": { "type": "boolean", "readonly": true },
      "vatIncluded": { "type": "boolean", "readonly": false },
      "bundle": { "type": "boolean", "readonly": true },
      "canBuyZero": { "type": "boolean", "readonly": false },
      "quantityTrace": { "type": "boolean", "readonly": false },
      "subscribe": { "type": "boolean", "readonly": false },
      "barcodeMulti": { "type": "boolean", "readonly": false },
      "withoutOrder": { "type": "boolean", "readonly": false },
      "dateActiveFrom": { "type": "datetime", "readonly": false },
      "dateActiveTo": { "type": "datetime", "readonly": false },
      "createdBy": { "type": "number", "readonly": true },
      "modifiedBy": { "type": "number", "readonly": true },
      "dateCreate": { "type": "datetime", "readonly": true },
      "timestampX": { "type": "datetime", "readonly": true },
      "code": { "type": "string", "readonly": false, "nullable": true },
      "xmlId": { "type": "string", "readonly": false },
      "sort": { "type": "number", "readonly": false },
      "vatId": { "type": "number", "readonly": false },
      "previewText": { "type": "string", "readonly": false },
      "detailText": { "type": "string", "readonly": false },
      "previewTextType": { "type": "string", "readonly": false },
      "detailTextType": { "type": "string", "readonly": false },
      "previewPicture": { "type": "object", "readonly": false },
      "detailPicture": { "type": "object", "readonly": false },
      "iblockSection": { "type": "object", "readonly": false },
      "width": { "type": "number", "readonly": false },
      "height": { "type": "number", "readonly": false },
      "length": { "type": "number", "readonly": false },
      "quantityReserved": { "type": "number", "readonly": false, "nullable": true },
      "recurSchemeLength": { "type": "number", "readonly": false },
      "recurSchemeType": { "type": "string", "readonly": false },
      "trialPriceId": { "type": "number", "readonly": false }
    },
    "aggregatable": ["purchasingPrice", "quantity", "iblockSectionId"],
    "batch": ["create", "update", "delete"]
  }
}

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

Full list of common API errors — Errors.

Known specifics

Writing depends on warehouse management. The quantity, purchasingPrice, and purchasingCurrency fields are marked as writable in the reference, but when warehouse management is enabled in the Bitrix24 account they are not applied when creating or updating a product — stock and purchase prices are managed by warehouse 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.

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