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

Search price types

POST /v1/catalog-price-types/search

Search price types with filters. The equivalent of GET /v1/catalog-price-types with filters, but over POST — more convenient for conditions across several fields.

Request body fields

Parameter Type Default Description
filter object — Filtering by the fields of GET /v1/catalog-price-types/fields.
Filtering syntax. Example: { "base": "Y" }
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records. Combined with a date-range filter wider than 14 days, the request is rejected — see UNSTABLE_OFFSET_PAGINATION in the "Errors" section
select string[] — Field selection: ["id", "name", "base"]
sort string — Sort field. The - prefix means descending: "sort": "-sort". The long form "order": { "sort": "desc" } is accepted too
autoWindow boolean true Split the result set into weekly windows when filtering by a date range wider than 14 days. false disables splitting

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-price-types/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "base": "Y" },
    "limit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-price-types/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "base": "Y" },
    "limit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-price-types/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { base: 'Y' },
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()
console.log('catalogGroupId of the base price:', data[0].id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-price-types/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { base: 'Y' },
    limit: 10,
  }),
})

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
meta.durationMs number Request duration in milliseconds

Response example

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"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false,
    "durationMs": 95
  }
}

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
400 UNSTABLE_OFFSET_PAGINATION offset above zero together with a date-range filter wider than 14 days. Send a single request with limit up to 5000, or autoWindow: false with an explicit sort: "id", or split the date range into parts
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

The base: "Y" filter is the shortest way to learn the catalogGroupId of the base price. It returns exactly one record, and its id is not necessarily 1.

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.

A date filter wider than 14 days is split into weekly windows. Vibecode splits such a dateCreate or timestampX range into windows on its own and merges the result. Together with an offset above zero this is not possible — 400 UNSTABLE_OFFSET_PAGINATION arrives; autoWindow: false disables the split.

Writing is not supported. POST /v1/catalog-price-types (without /search), PATCH and DELETE return 404 ROUTE_NOT_FOUND — price types are created in the Bitrix24 interface.

See also