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 service fields. Catalog properties of the form propertyNNN are not included: their values arrive in the GET /v1/catalog-services/:id response, and their names and types in GET /v1/catalog-product-properties.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-services/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-services/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-services/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 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

¹ 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: number, string, boolean, datetime, object
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.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 in every response of this method

Response example

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 full response contains 28 fields.

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

fields_partial always arrives and a retry does not clear it. The warning advises repeating the request, but a retry returns the same response, and the ?iblockId= parameter does not change it. The 28 fields of the reference are complete — only the catalog properties propertyNNN are missing.

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.

See also