Para agentes de IA: markdown desta página — /docs-content-en/entities/catalog-services.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Catalog services

Services of the product catalog: list, get, create, update, and delete. A service is a catalog record of type 7 for work and service jobs, such as installation or delivery. A service has no warehouse fields — stock, weight, and purchase price; sale prices are set in Catalog prices.

Bitrix24 API: catalog.product.service.* Scope: catalog

Create a service

POST /v1/catalog-services

Creates a service in the product catalog. Fields are passed flat at the root of the JSON.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionService name
FieldiblockId Typenumber Requiredyes DescriptionProduct catalog ID — a catalog whose productIblockId is not filled in. List: GET /v1/catalogs
FieldiblockSectionId Typenumber Requiredno DescriptionCatalog section ID. List: GET /v1/catalog-sections
FieldiblockSection Typearray Requiredno DescriptionArray of catalog section IDs, if the service belongs to several sections. The first ID of the array becomes the main section iblockSectionId. List: GET /v1/catalog-sections
Fieldactive Typeboolean Requiredno DescriptionWhether the service is active. Defaults to true
Fieldavailable Typeboolean Requiredno DescriptionWhether the service is available for purchase. Defaults to false
Fieldmeasure Typenumber Requiredno DescriptionUnit of measure ID. List: GET /v1/catalog-measures
FieldvatIncluded Typeboolean Requiredno DescriptionVAT is included in the price
FieldvatId Typenumber Requiredno DescriptionVAT rate ID. List: GET /v1/catalog-vat-rates
Fieldcode Typestring Requiredno DescriptionSymbolic code
FieldxmlId Typestring Requiredno DescriptionExternal code. If omitted, the response returns the service id as a string in this field
Fieldsort Typenumber Requiredno DescriptionSort order. Defaults to 500
FieldpreviewText Typestring Requiredno DescriptionPreview text
FieldpreviewTextType Typestring Requiredno DescriptionPreview text format: text or html. Defaults to text
FielddetailText Typestring Requiredno DescriptionDetailed description
FielddetailTextType Typestring Requiredno DescriptionDetailed description format: text or html. Defaults to text
FieldpreviewPicture Typeobject Requiredno DescriptionPreview picture
FielddetailPicture Typeobject Requiredno DescriptionDetail picture
FieldpropertyNNN Typestring Requiredno DescriptionCatalog property value, where NNN is the property id from GET /v1/catalog-product-properties. A string property accepts a string: "property301": "A-100"

Fields marked readonly: true in Service fields are filled in by the system — for example, type and createdBy. Such a field in the body is rejected with 400 READONLY_FIELD. The sale price is set separately via POST /v1/catalog-prices with the service id in productId.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-services" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Air conditioner installation",
    "iblockId": 25,
    "iblockSectionId": 281,
    "measure": 9,
    "vatIncluded": true
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-services" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Air conditioner installation",
    "iblockId": 25,
    "iblockSectionId": 281,
    "measure": 9,
    "vatIncluded": true
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Air conditioner installation',
    iblockId: 25,
    iblockSectionId: 281,
    measure: 9,
    vatIncluded: true,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Air conditioner installation',
    iblockId: 25,
    iblockSectionId: 281,
    measure: 9,
    vatIncluded: true,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionFull object of the created service. The field set is the same as in GET /v1/catalog-services/:id

Response example

The main fields are shown.

JSON 
{
  "success": true,
  "data": {
    "id": 7231,
    "iblockId": 25,
    "iblockSectionId": 281,
    "iblockSection": [281],
    "name": "Air conditioner installation",
    "type": 7,
    "active": true,
    "available": false,
    "code": null,
    "xmlId": "7231",
    "sort": 500,
    "measure": 9,
    "vatId": null,
    "vatIncluded": true,
    "previewText": null,
    "previewTextType": "text",
    "createdBy": 1295,
    "modifiedBy": 1295,
    "dateCreate": "2026-10-08T20:50:59.000Z",
    "timestampX": "2026-10-08T20:50:59.000Z"
  }
}

Error response example

422 — the name was not passed:

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

Errors

HTTP Code Description
HTTP422 CodeBITRIX_ERROR Descriptionname was not passed (Required fields: name)
HTTP422 CodeBITRIX_ERROR DescriptioniblockId was not passed, or no catalog with this iblockId exists (iblock is not catalog)
HTTP422 CodeBITRIX_ERROR DescriptioniblockId contains the ID of an offers catalog rather than a product catalog (productType is not allowed for this catalog)
HTTP400 CodeEMPTY_CREATE_BODY DescriptionThe request body is empty
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe body contains an object under fields instead of root-level fields; the service is not created
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field filled in by the system, for example type or createdBy
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed

Full list of common API errors — Errors.

Known specifics

A new service is not available for purchase. If available is not passed, the service is created with available: false. To make the service sellable right away, pass "available": true on creation or later in PATCH /v1/catalog-services/:id.

Unknown scalar fields are not rejected. A name that is not among the service fields is skipped in the create body: the service is created without it, and the response is 201. An object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE before creation — send fields at the JSON root. Check names against Service fields.

See also