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

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

Create a product property

POST /v1/catalog-product-properties

Creates a product property in the catalog. Fields are passed flat at the root of the JSON. The response returns the full object of the created property.

Request fields (body)

Field Type Req. Description
iblockId number yes Catalog ID. List: GET /v1/catalogs
name string yes Display name of the property
propertyType string yes Base type. N number, S string, L list, F file, E element binding, G section binding
code string no Symbolic code. Latin letters, digits, underscore. First character is not a digit
active boolean no Whether the property is active. Defaults to true
sort number no Sort index
defaultValue string no Default value
userType string no User type, for example directory, DateTime, Money, HTML
userTypeSettings object no User type settings
listType string no List appearance. L dropdown, C checkboxes
multiple boolean no Multiple value
multipleCnt number no Number of inputs for multiple values
withDescription boolean no Value description field
searchable boolean no Participates in search
filtrable boolean no Participates in the filter
isRequired boolean no Required to fill in
linkIblockId number no Linked catalog ID for binding types
fileType string no Allowed file extensions for type F
xmlId string no External ID
hint string no Field hint

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-product-properties" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 19,
    "name": "Material",
    "propertyType": "S"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-product-properties" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 19,
    "name": "Material",
    "propertyType": "S"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-product-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 19,
    name: 'Material',
    propertyType: 'S',
  }),
})

const { success, data } = await res.json()
console.log('Property ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-product-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 19,
    name: 'Material',
    propertyType: 'S',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object Full object of the created property. The field set is the same as GET /v1/catalog-product-properties/:id

The id of the created property matches NNN in the propertyNNN key, under which this property's value is returned for a product in Catalog products:

propertyNNN  →  property659

NNN is the value of the id field. It is used to build the id → name mapping that labels propertyNNN values.

Response example

The main fields are shown.

JSON 
{
  "success": true,
  "data": {
    "id": 659,
    "iblockId": 19,
    "name": "Material",
    "propertyType": "S",
    "code": "s12",
    "active": true,
    "sort": null,
    "defaultValue": null,
    "userType": "directory",
    "userTypeSettings": {
      "group": "N",
      "multiple": "N",
      "size": 1,
      "tableName": "b_hlbd_categories",
      "width": 0
    },
    "listType": "L",
    "multiple": false,
    "multipleCnt": null,
    "withDescription": null,
    "searchable": false,
    "filtrable": false,
    "isRequired": false,
    "linkIblockId": null,
    "fileType": null,
    "xmlId": null,
    "hint": null,
    "timestampX": "2026-03-19T18:23:02.000Z"
  }
}

Error response example

422 — a required field was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: name"
  }
}

Errors

HTTP Code Description
422 BITRIX_ERROR A required field was not passed — the message lists the missing ones (Required fields: name, Required fields: propertyType)
422 BITRIX_ERROR The catalog with the specified iblockId was not found (Iblock Not Found)
400 READONLY_FIELD A read-only field was passed in the body, for example id or timestampX
403 SCOPE_DENIED The key lacks the catalog scope
401 MISSING_API_KEY The X-Api-Key header was not passed

Full list of common API errors — Errors.

See also