Para agentes de IA: markdown desta página — /docs-content-en/entities/catalog-vat-rates.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Catalog VAT rates

Reference data for product catalog VAT rates: names, percentages, status, and sort order. Pass a rate's identifier as the product's vatId.

Bitrix24 API: catalog.vat.* Scope: catalog

Create a VAT rate

POST /v1/catalog-vat-rates

Adds a VAT rate to the product catalog's list of VAT rates. The request body is flat, without a fields wrapper.

Request body fields

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionVAT rate name.
Fieldrate Typenumber Requiredyes DescriptionVAT percentage. Fractional numbers and 0 are accepted. null is not accepted.
Fieldactive Typestring Requiredno DescriptionStatus: Y or N. Other values and null are rejected.
Fieldsort Typenumber Requiredno DescriptionSort order, an integer of at least 1. null is not accepted.

id and timestampX are read-only. See VAT rate fields for the full list.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-vat-rates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs VAT 2026-10-08",
  "rate": 7.5,
  "active": "N",
  "sort": 900
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-vat-rates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs VAT 2026-10-08",
  "rate": 7.5,
  "active": "N",
  "sort": 900
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-vat-rates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Docs VAT 2026-10-08",
    "rate": 7.5,
    "active": "N",
    "sort": 900
  }),
})

const { success, data } = await res.json()
console.log('ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-vat-rates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Docs VAT 2026-10-08",
    "rate": 7.5,
    "active": "N",
    "sort": 900
  }),
})

const { success, data } = await res.json()
console.log('ID:', data.id)

Response fields

The response has status 201 and contains the complete created record.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata Typeobject DescriptionVAT rate object.
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.warnings Typearray DescriptionFor an unknown field name, contains an UNRECOGNIZED_WRITE_FIELD warning with code, field, and message keys. On a route that wraps the field map itself, an object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE when the schema does not declare fields; pass fields flat at the JSON root.

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

Error response example

400 — rate is missing. No record is created:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"rate\" is required to create catalogVatRate."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionname or rate is missing, null, or an empty string. The message names the first missing field.
HTTP400 CodeINVALID_PARAMS DescriptionAn invalid field type, active outside Y/N, or a fractional or non-positive sort. active and sort cannot be null.
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains id or timestampX. Remove the field from the request.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. See error.message for the reason and error.b24Code for the original code.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionWrites are blocked: the key is read-only.
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 scalar field may not be saved. It does not bypass required-field validation. The response may contain meta.warnings with UNRECOGNIZED_WRITE_FIELD. Check names against VAT rate fields and verify the values in data.

See also