Für KI-Agenten: Markdown dieser Seite — /docs-content-en/entities/catalog-price-types.md Dokumentationsindex — /llms.txt

Dokumentationsartikel sind derzeit auf Englisch verfügbar.

Catalog price types

Price types of your Bitrix24 account: list, retrieve and filter. A price type is what catalog prices pass in the catalogGroupId field. Price types are read-only: they are configured in the Bitrix24 interface.

Bitrix24 API: catalog.priceType.* Scope: catalog

List price types

GET /v1/catalog-price-types

Returns the price types configured in your Bitrix24 account, with filtering, sorting and field selection.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). With limit > 50 the response is assembled automatically from several Bitrix24 pages
offset number 0 Skip N records. Together with limit it defines the selection window
select string — Field selection: ?select=id,name,base. Only the listed fields are returned
sort string — Sort field. The - prefix means descending: ?sort=-sort. The same sort in the long form: ?order[sort]=desc
filter object — Filtering by the fields of GET /v1/catalog-price-types/fields.
Filtering syntax. Example: ?filter[base]=Y

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data, meta } = await res.json()
const basePriceType = data.find(t => t.base === 'Y')
console.log('catalogGroupId of the base price:', basePriceType.id)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of price types (all fields — see Price type fields)
meta.total number Total number of price types matching the filter
meta.hasMore boolean Whether more records exist beyond limit

Response example

The response to GET /v1/catalog-price-types?limit=2 — two of the five price types configured on the account:

JSON 
{
  "success": true,
  "data": [
    {
      "base": "Y",
      "createdBy": 1,
      "dateCreate": "2020-04-22T05:37:42.000Z",
      "id": 1,
      "modifiedBy": 1,
      "name": "BASE",
      "sort": 100,
      "timestampX": "2024-10-22T04:31:37.000Z",
      "xmlId": "BASE"
    },
    {
      "base": "N",
      "createdBy": 29,
      "dateCreate": "2021-04-20T12:56:47.000Z",
      "id": 3,
      "modifiedBy": 1,
      "name": "2base",
      "sort": 100,
      "timestampX": "2024-10-22T04:31:36.000Z",
      "xmlId": null
    }
  ],
  "meta": {
    "total": 5,
    "hasMore": true
  }
}

The numbers in the example come from one specific account. On yours they will differ: detect the base type by base: "Y", not by the value of id.

Error response example

400 — filtering by a field that does not exist:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'nonExistentField' for entity 'catalog-price-types'. Available: id, name, base, xmlId, sort, createdBy, modifiedBy, dateCreate, timestampX"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filtering by a field a price type does not have. The message lists the available fields
400 UNKNOWN_SORT_FIELD Sorting by a field a price type does not have
422 BITRIX_ERROR Bitrix24 refused to read price types: the key owner has no portal administrator rights
403 SCOPE_DENIED The API key does not carry the catalog scope
401 MISSING_API_KEY The X-Api-Key header is missing
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

The full list of common API errors — Errors.

Known specifics

There is exactly one base price type. The filter ?filter[base]=Y returns a single record — its id is the catalogGroupId of the base price for POST /v1/catalog-prices.

The method requires administrator rights. The catalog scope is not enough: Bitrix24 returns price types only to a key whose owner has the Bitrix24 account administrator role. Otherwise a 422 BITRIX_ERROR arrives with a Bitrix24 message about insufficient rights.

Paging through offset is supported. Vibecode returns the requested window [offset, offset + limit): meta.total is the exact number of records matching the filter, meta.hasMore tells whether records exist beyond the window.

When to use search instead of list: for conditions over several fields, POST /v1/catalog-price-types/search is more convenient — the filter travels in the request body.

See also