CRM product fields

GET /v1/products/fields

Returns the product field schema: 22 standard fields and the custom catalog properties of the form PROPERTY_<N> configured in the Bitrix24 account. Every field carries a label, a type, and a read-only flag. Fields that need further explanation also carry a description, and fields with a fixed value set carry an enum dictionary.

Standard fields

Each field is described by an object { type, readonly }. The writeOnly: true marker identifies a write-only name, while notReturned: true identifies a name absent from responses. The list, get, search, create, and update responses use canonical camelCase names. currencyId is a write alias: response data carries the currency under currency. If both names are present, currency wins. An explicit select=currencyId is rejected with 400 SELECT_FIELD_NOT_RETURNED. Use select=currency for reads. The native Bitrix24 name select=CURRENCY_ID remains valid and also returns the value under the canonical currency key.

Custom properties

Catalog properties come back as additional keys of the form PROPERTY_<N> with the type product_property. Each is described by an object { type, readonly, label }, where label is the property name in the Bitrix24 account language. The property set depends on the catalog settings: one Bitrix24 account may return "SKU", "Manufacturer", and "Color", while another returns a list of its own. The values of these properties are returned in the GET /v1/products/:id response, and in list and search responses when you include the property name in select.

Examples

curl — personal key

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

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/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/products/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log('Total fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language. Enum values carry an English label.

Response example

A subset of fields is shown. The actual number of PROPERTY_<N> properties depends on the catalog settings in the Bitrix24 account.

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "Product identifier" },
      "name": { "type": "string", "readonly": false, "label": "Product name" },
      "active": { "type": "boolean", "readonly": false, "label": "Active", "description": "Whether the product is active." },
      "price": { "type": "number", "readonly": false, "label": "Product price" },
      "currencyId": {
        "type": "string",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Price currency (alias)",
        "description": "Write alias of currency. Responses return the value under currency. If both names are present, currency wins. List: GET /v1/currencies."
      },
      "currency": {
        "type": "string",
        "readonly": false,
        "label": "Price currency",
        "description": "Currency of the price. Write alias: currencyId. If both names are present, currency wins. Available values: GET /v1/currencies."
      },
      "descriptionType": {
        "type": "string",
        "readonly": false,
        "label": "Description format",
        "description": "Format of the description field: plain text or HTML markup.",
        "enum": [
          { "value": "text", "label": "Plain text" },
          { "value": "html", "label": "HTML" }
        ]
      },
      "vatIncluded": { "type": "boolean", "readonly": false, "label": "VAT included", "description": "Whether the VAT is already included in the price." },
      "createdAt": { "type": "datetime", "readonly": true, "label": "Creation date" },

      "PROPERTY_301": { "type": "product_property", "readonly": false, "label": "SKU" },
      "PROPERTY_303": { "type": "product_property", "readonly": false, "label": "Manufacturer" },
      "PROPERTY_307": { "type": "product_property", "readonly": false, "label": "Color" }
    }
  }
}

Error response example

403 — no scope:

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

Errors

For the full list of common API errors, see Errors.

Known specifics

The same product in the catalog has more fields. The product with the same id is available via GET /v1/catalog-products, where it has a wider field set — stock, warehouse, and variations.

A PROPERTY_<N> descriptor carries the property name only — it holds no list options. The descriptor object is exactly { type: "product_property", readonly, label }: no items, no values, no list of allowed values whatsoever. So this endpoint tells you that property 301 is called "SKU", but nothing here resolves the selected option's identifier into its text.

Where to go for the values:

Here NNN is the number from the PROPERTY_<N> key: it is the same value, the catalog property id. All three catalog calls require the catalog scope — a key carrying only crm gets 403 SCOPE_DENIED.

See also

• Get CRM product
• List CRM products
• Aggregate CRM products
• Entity API
• Catalog products
• Catalog product properties
• List-property values