## 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 | |------|-----|:-----:|---------| | `name` | string | yes | Service name | | `iblockId` | number | yes | Product catalog ID — a catalog whose `productIblockId` is not filled in. List: [`GET /v1/catalogs`](/docs/entities/catalogs/list) | | `iblockSectionId` | number | no | Catalog section ID. List: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections/list) | | `iblockSection` | array | no | Array 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`](/docs/entities/catalog-sections/list) | | `active` | boolean | no | Whether the service is active. Defaults to `true` | | `available` | boolean | no | Whether the service is available for purchase. Defaults to `false` | | `measure` | number | no | Unit of measure ID. List: [`GET /v1/catalog-measures`](/docs/entities/catalog-measures/list) | | `vatIncluded` | boolean | no | VAT is included in the price | | `vatId` | number | no | VAT rate ID. List: [`GET /v1/catalog-vat-rates`](/docs/entities/catalog-vat-rates/list) | | `code` | string | no | Symbolic code | | `xmlId` | string | no | External code. If omitted, the response returns the service `id` as a string in this field | | `sort` | number | no | Sort order. Defaults to `500` | | `previewText` | string | no | Preview text | | `previewTextType` | string | no | Preview text format: `text` or `html`. Defaults to `text` | | `detailText` | string | no | Detailed description | | `detailTextType` | string | no | Detailed description format: `text` or `html`. Defaults to `text` | | `previewPicture` | object | no | Preview picture | | `detailPicture` | object | no | Detail picture | | `propertyNNN` | string | no | Catalog property value, where `NNN` is the property `id` from [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list). A string property accepts a string: `"property301": "A-100"` | Fields marked `readonly: true` in [Service fields](./fields.md) 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`](/docs/entities/catalog-prices/create) with the service `id` in `productId`. ## Examples ### curl — personal key ```bash 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 ```bash 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 | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | Full object of the created service. The field set is the same as in [`GET /v1/catalog-services/:id`](./get.md) | ## 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 | |------|-----|----------| | 422 | `BITRIX_ERROR` | `name` was not passed (`Required fields: name`) | | 422 | `BITRIX_ERROR` | `iblockId` was not passed, or no catalog with this `iblockId` exists (`iblock is not catalog`) | | 422 | `BITRIX_ERROR` | `iblockId` contains the ID of an offers catalog rather than a product catalog (`productType is not allowed for this catalog`) | | 400 | `EMPTY_CREATE_BODY` | The request body is empty | | 400 | `READONLY_FIELD` | The body contains a field filled in by the system, for example `type` or `createdBy` | | 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](/docs/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`](./update.md). **Unknown 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`. Check names against [Service fields](./fields.md). ## See also - [List services](/docs/entities/catalog-services/list) - [Get a service](/docs/entities/catalog-services/get) - [Update a service](/docs/entities/catalog-services/update) - [Delete a service](/docs/entities/catalog-services/delete) - [Catalog prices](/docs/entities/catalog-prices) - [Catalog sections](/docs/entities/catalog-sections) - [Batch](/docs/batch) - [Limits and optimization](/docs/optimization)