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

Search VAT rates

POST /v1/catalog-vat-rates/search

Searches VAT rates in the product catalog using conditions in the JSON request body. Conditions on multiple fields are specified as a nested structure in the request body.

Request body fields

Field Type Required Description
Fieldfilter Typeobject Requiredno DescriptionFilter by fields from GET /v1/catalog-vat-rates/fields.
Filtering syntax. Example: {"active": "Y"}.
Fieldsort Typestring | object | array Requiredno DescriptionA string "-rate", an object {"rate": "desc"}, or an array of strings ["-rate", "id"]. Defaults to ascending id.
Fieldorder Typeobject Requiredno DescriptionObject-form alias for sort. If both are provided, sort takes precedence.
Fieldselect Typestring[] Requiredno DescriptionFields to return: ["id", "name", "rate"]. The string "id,name,rate" is also accepted.
Fieldlimit Typenumber Requiredno DescriptionNumber of records, from 1 to 5000. Defaults to 50.
Fieldoffset Typenumber Requiredno DescriptionSkip N records. Defaults to 0.
FieldwithTotal Typeboolean Requiredno DescriptionRequest the record count. For this reference entity, false does not suppress meta.total.
FieldautoWindow Typeboolean Requiredno DescriptionAutomatically split large result sets into date windows. Enabled by default. Use regular limit and offset for a small reference list.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-vat-rates/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "id": 25
  },
  "sort": "-rate",
  "limit": 2
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-vat-rates/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "id": 25
  },
  "sort": "-rate",
  "limit": 2
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-vat-rates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "id": 25
    },
    "sort": "-rate",
    "limit": 2
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-vat-rates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "id": 25
    },
    "sort": "-rate",
    "limit": 2
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata Typearray DescriptionArray of VAT rates.
Fielddata[].id Typenumber DescriptionVAT rate identifier. List: GET /v1/catalog-vat-rates. Pass it as the product's vatId.
Fielddata[].name Typestring DescriptionVAT rate name.
Fielddata[].rate Typenumber | null DescriptionVAT percentage. For an existing "No VAT" rate, this field may be null.
Fielddata[].active Typestring DescriptionRate status: Y — active, N — inactive.
Fielddata[].sort Typenumber DescriptionSort order.
Fielddata[].timestampX Typestring DescriptionModification date and time in ISO 8601 format. Set by Bitrix24.
Fieldmeta.total Typenumber DescriptionNumber of rates matching the filter. Returned even with withTotal=false.
Fieldmeta.hasMore Typeboolean DescriptionWhether more rates exist beyond limit.
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds.
Fieldmeta.warnings Typearray DescriptionPresent when there are warnings: UNKNOWN_SELECT_FIELD for an unknown name in select, LIMIT_ZERO_IGNORED when limit is 0 and the default is used.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "active": "N",
      "id": 25,
      "name": "Docs VAT 2026-10-08",
      "rate": 7.5,
      "sort": 900,
      "timestampX": "2026-10-08T18:49:59.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false,
    "durationMs": 80
  }
}

Error response example

400 — sorting by nope, which is not in the schema:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_SORT_FIELD",
    "message": "Unknown sort field 'nope' for entity 'catalog-vat-rates'. Available: id, name, rate, active, sort, timestampX"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionThe filter references a field outside the schema. The message lists available fields.
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionThe sort order references a field outside the schema.
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator or a logical key $or, $and, $not. Use $in for multiple values of one field.
HTTP400 CodeINVALID_FILTER Descriptionfilter is not an object of conditions.
HTTP400 CodeINVALID_SORT_TYPE Descriptionsort is not a string, an object, or an array of strings.
HTTP400 CodeINVALID_SELECT_TYPE Descriptionselect is not a string or an array of strings.
HTTP400 CodeINVALID_LIMIT Descriptionlimit is not a number.
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the catalog scope.
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 tokens. For an OAuth application key, check the user session.

For all common API errors, see Errors.

Known specifics

An empty object {} is valid. With no conditions, search returns the regular list of rates.

An unknown name in select does not stop the request. Check meta.warnings: UNKNOWN_SELECT_FIELD identifies a field that may be absent from the results.

See also