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
Parameterlimit (query) Typenumber Default50 DescriptionNumber of records, from 1 to 5000. A non-numeric value is replaced with 50.
Parameteroffset (query) Typenumber Default0 DescriptionSkip N records. ?offset=1 starts with the second record. Multiples of 50 are not required.
Parameterselect (query) Typestring Default— DescriptionComma-separated fields to return: ?select=id,name,rate. See VAT rate fields for names.
Parametersort (query) Typestring Defaultid DescriptionSort order: ?sort=-rate, where minus means descending. Separate multiple fields with commas: ?sort=sort,id.
Parameterorder (query) Typeobject Default— DescriptionObject-form sort order: ?order[rate]=desc. If sort is also provided, it takes precedence.
Parameterfilter (query) Typeobject Default— DescriptionFilter by fields from GET /v1/catalog-vat-rates/fields.
Filtering syntax. Example: ?filter[active]=Y.
ParameterwithTotal (query) Typestring Default— DescriptionRequest 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
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.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
  }
}

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
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 Descriptionfilter is not a JSON object, or filter[field]=… and filter={...} are mixed. Use one form.
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator or a logical key $or, $and, $not. Use $in for multiple values of one field.
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 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