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

List VAT rates

GET /v1/catalog-vat-rates

Returns VAT rates from the product catalog with filtering and sorting.

Parameters

Parameter Type Default Description
limit (query) number 50 Number of records, from 1 to 5000. A non-numeric value is replaced with 50.
offset (query) number 0 Skip N records. ?offset=1 starts with the second record. Multiples of 50 are not required.
select (query) string — Comma-separated fields to return: ?select=id,name,rate. See VAT rate fields for names.
sort (query) string id Sort order: ?sort=-rate, where minus means descending. Separate multiple fields with commas: ?sort=sort,id.
order (query) object — Object-form sort order: ?order[rate]=desc. If sort is also provided, it takes precedence.
filter (query) object — Filter by fields from GET /v1/catalog-vat-rates/fields.
Filtering syntax. Example: ?filter[active]=Y.
withTotal (query) string — Request the record count: true or false. For this reference entity, false does not suppress meta.total. Pagination and record counts.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-vat-rates?filter[id]=25&limit=1&withTotal=true" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-vat-rates?filter[id]=25&limit=1&withTotal=true" \
  -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-vat-rates?filter[id]=25&limit=1&withTotal=true', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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?filter[id]=25&limit=1&withTotal=true', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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.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
  }
}

Error response example

400 — the filter references nope, which is not in the schema:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter 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 filter is not a JSON object, or filter[field]=… and filter={...} are mixed. Use one form.
400 INVALID_FILTER_OPERATOR An unknown operator or a logical key $or, $and, $not. Use $in for multiple values of one field.
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 unknown name in select does not stop the request. The response is 200, records retain the available fields, and meta.warnings contains UNKNOWN_SELECT_FIELD. Check warnings to catch typos.

A No VAT rate may have rate: null. This differs from a numeric rate of 0. Handle it explicitly when displaying rates or calculating totals.

See also