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

Service fields

GET /v1/catalog-services/fields

Returns the catalog service field reference with labels, types, write flags and dictionaries of allowed values, plus the fields available for aggregation and the operations available in a batch request.

The reference contains 28 static service fields. Pass ?iblockId=<catalog ID> to also receive catalog properties of the form propertyNNN when Bitrix24 returns the dynamic field metadata successfully. Get the catalog ID from GET /v1/catalogs. Property values arrive in the GET /v1/catalog-services/:id response; their names and types are also available from GET /v1/catalog-product-properties.

Parameters

Parameter	Type	Required	Description
`iblockId` (query)	number	no	Product catalog ID from `GET /v1/catalogs` — a catalog whose `productIblockId` is empty. With it, a successful response is extended with the catalog properties `propertyNNN`. Without it, and also when Bitrix24 refuses the dynamic field metadata (for example, no catalog has that ID), the response has 28 static fields and the `fields_partial` warning in `meta.warnings`

Examples

curl — personal key

Terminal

curl "https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl "https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25" \
  -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-services/fields?iblockId=25', {
  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-services/fields?iblockId=25', {
  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 keyed by field name; each value contains the type, the write flags, a display label and — for fields with a fixed set of values — their dictionary. The set of keys is broken down in the table after the field list. data.aggregatable lists the fields for groupBy in aggregation. data.batch lists the operations available in a batch request.

Field	Type	RO	Description
`id`	number	yes	Service ID
`name`	string	no	Service name. Required on create
`active`	boolean	no	Whether the service is active
`available`	boolean	no	Whether the service is available for purchase. Without an explicit value, the service is created with `false`
`iblockId`	number	no¹	Product catalog ID. List: `GET /v1/catalogs`. Required on create, set on create only
`type`	number	yes	Record type, always `7` for a service. Set by Bitrix24
`iblockSectionId`	number \| null	no	Primary catalog section ID. `null` — the service is not linked to a section. List: `GET /v1/catalog-sections`
`iblockSection`	object	no	Array of IDs of all catalog sections the service belongs to. Returned in the single-service response, not supported in the list `select`. List: `GET /v1/catalog-sections`
`measure`	number	no	Unit of measure ID. List: `GET /v1/catalog-measures`
`vatIncluded`	boolean	no	VAT is included in the price
`vatId`	number	no	VAT rate ID. List: `GET /v1/catalog-vat-rates`
`bundle`	boolean	yes	Whether the service is a bundle. Computed by Bitrix24
`code`	string \| null	no	Symbolic code. `null` if not set
`xmlId`	string	no	External identifier. If not set, equals the service `id` as a string
`sort`	number	no	Sort order. Defaults to `500`
`dateActiveFrom`	datetime	no	Activity start date
`dateActiveTo`	datetime	no	Activity end date
`createdBy`	number	yes	ID of the user who created the service. List: `GET /v1/users`
`modifiedBy`	number	yes	ID of the user who last modified the service. List: `GET /v1/users`
`dateCreate`	datetime	yes	Creation date
`timestampX`	datetime	yes	Last modification date
`previewText`	string	no	Preview text
`previewTextType`	string	no	Preview text format: `text` or `html`
`detailText`	string	no	Detailed description
`detailTextType`	string	no	Detailed description format: `text` or `html`
`previewPicture`	object	no	Preview image
`detailPicture`	object	no	Detail image
`priceType`	string	no	Declared in the reference, but not returned in the list or single-service responses. Service prices are set via `POST /v1/catalog-prices`
`propertyNNN`	productproperty	no	Catalog property, where `NNN` is the property `id` from `GET /v1/catalog-product-properties`. Returned only with `iblockId`; multiple-value properties carry `multiple: true`. The type arrives from Bitrix24 as is and is not one of the five static-field types

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

Field labels label and descriptions description arrive in English. Fields with a fixed set of values — previewTextType and detailTextType — also carry an enum dictionary: an array of { value, label }. Send value; label is meant for display.

Field	Type	Description
`success`	boolean	Always `true` on success
`data.fields.<name>.type`	string	Field type. For the 28 static fields — `number`, `string`, `boolean`, `datetime`, `object`. For the dynamic catalog fields returned with `iblockId` — the Bitrix24 type as is, for example `productproperty` for a catalog property
`data.fields.<name>.label`	string	Short field label
`data.fields.<name>.description`	string	Extended field description: its purpose, where to get the list of allowed values, write-time behavior
`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>.writeOnly`	boolean	`true` — the field is accepted on write. Present on `iblockSection`
`data.fields.<name>.notReturned`	boolean	`true` — the field name is not supported in `select`: list and search reject it with `SELECT_FIELD_NOT_RETURNED`. Present on `iblockSection`
`data.fields.<name>.nullable`	boolean	`true` — the field can come back as `null`. The key is present only on such fields
`data.fields.<name>.multiple`	boolean	`true` — the dynamic catalog field stores several values and arrives as an array. The key is present only on such fields
`data.fields.<name>.items`	array	List items of a dynamic field of type `enumeration`, as Bitrix24 returned them. The key is present only on such fields
`data.fields.<name>.values`	array	Dictionary of a dynamic field's values: an array of `{ value, label }`. The key is present when Bitrix24 returned such a dictionary
`data.fields.<name>.default`	number \| string \| boolean \| null	Default value of a dynamic field. The key is present when Bitrix24 returned it as a scalar or `null`
`data.aggregatable`	string[]	Fields for `groupBy` in aggregation: `iblockSectionId`
`data.batch`	string[]	Service operations available in a batch request: `create`, `update`, `delete`
`meta.warnings`	array	Warnings. An element with `code: fields_partial` arrives without `iblockId` or when Bitrix24 does not return the dynamic field metadata

Response example

Response without iblockId: static fields only, with the fields_partial warning.

JSON

{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Service identifier",
        "description": "Unique identifier of the catalog service."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "label": "Catalog ID",
        "description": "Catalog the service belongs to. Available values: GET /v1/catalogs. Set on create only — changing it via PATCH is rejected, a service cannot be moved between catalogs."
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Service type",
        "description": "Bitrix24 service type (7); set by Bitrix24 and read only."
      },
      "iblockSectionId": {
        "type": "number",
        "readonly": false,
        "nullable": true,
        "label": "Catalog section ID",
        "description": "Primary catalog section of the service; null when it is not linked to a section. Available values: GET /v1/catalog-sections."
      },
      "iblockSection": {
        "type": "object",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Catalog sections",
        "description": "Array of catalog section IDs the service 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": [
      "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 six fields — one each for the readonly and createOnly flags, the computed type, nullable, the writeOnly + notReturned pair and the enum dictionary. The static reference contains 28 fields; a successful response with iblockId contains the same static fields plus the catalog properties propertyNNN, and carries no fields_partial warning. For a catalog property, type arrives from Bitrix24 as is (productproperty), a multiple-value property carries multiple: true, and when Bitrix24 returned a value dictionary or a default, the keys values, items and default are present too.

Error response example

401 — the key was not passed:

JSON

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

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
429	`RATE_LIMITED`	Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the `x-ratelimit-limit` header (the cap is divided across replicas). Retry after the delay in the `Retry-After` header

Full list of common API errors — Errors.

Known specifics

Catalog properties require iblockId. Without a catalog ID, the response contains static fields and fields_partial. With ?iblockId=<catalog ID>, a successful Bitrix24 response adds propertyNNN properties to the reference and the warning is absent. If Bitrix24 does not return the dynamic fields, the static response with the warning is preserved.

Some fields are not returned in the list by default. The symbolic code code, the external code xmlId, the sort order sort, the VAT rate vatId, the texts, the images and the propertyNNN properties are not returned in the GET /v1/catalog-services response without an explicit ?select=. List the names you need in select to get them in the list. The single-service response, GET /v1/catalog-services/:id, always returns them.