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
filter object no Filter by fields from GET /v1/catalog-vat-rates/fields.
Filtering syntax. Example: {"active": "Y"}.
sort string | object | array no A string "-rate", an object {"rate": "desc"}, or an array of strings ["-rate", "id"]. Defaults to ascending id.
order object no Object-form alias for sort. If both are provided, sort takes precedence.
select string[] no Fields to return: ["id", "name", "rate"]. The string "id,name,rate" is also accepted.
limit number no Number of records, from 1 to 5000. Defaults to 50.
offset number no Skip N records. Defaults to 0.
withTotal boolean no Request the record count. For this reference entity, false does not suppress meta.total.
autoWindow boolean no Automatically 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
success boolean Always true on success.
data array Array of VAT rates.
data[].id number VAT rate identifier. List: GET /v1/catalog-vat-rates. Pass it as the product's vatId.
data[].name string VAT rate name.
data[].rate number | null VAT percentage. For an existing "No VAT" rate, this field may be null.
data[].active string Rate status: Y — active, N — inactive.
data[].sort number Sort order.
data[].timestampX string Modification date and time in ISO 8601 format. Set by Bitrix24.
meta.total number Number of rates matching the filter. Returned even with withTotal=false.
meta.hasMore boolean Whether more rates exist beyond limit.
meta.durationMs number Request duration in milliseconds.
meta.warnings array Present 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
400 UNKNOWN_FILTER_FIELD The filter references a field outside the schema. The message lists available fields.
400 UNKNOWN_SORT_FIELD The sort order references a field outside the schema.
400 INVALID_FILTER_OPERATOR An unknown operator or a logical key $or, $and, $not. Use $in for multiple values of one field.
400 INVALID_FILTER filter is not an object of conditions.
400 INVALID_SORT_TYPE sort is not a string, an object, or an array of strings.
400 INVALID_SELECT_TYPE select is not a string or an array of strings.
400 INVALID_LIMIT limit is not a number.
403 SCOPE_DENIED The key does not have the catalog scope.
401 MISSING_API_KEY The X-Api-Key header is missing.
401 TOKEN_MISSING The 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