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

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
name string yes VAT rate name.
rate number yes VAT percentage. Fractional numbers and 0 are accepted. null is not accepted.
active string no Status: Y or N. Other values and null are rejected.
sort number no Sort 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
success boolean Always true on success.
data object VAT rate object.
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.warnings array For an unknown field name, contains an UNRECOGNIZED_WRITE_FIELD warning with code, field, and message keys.

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
400 MISSING_REQUIRED_FIELDS name or rate is missing, null, or an empty string. The message names the first missing field.
400 INVALID_PARAMS An invalid field type, active outside Y/N, or a fractional or non-positive sort. active and sort cannot be null.
400 READONLY_FIELD The body contains id or timestampX. Remove the field from the request.
422 BITRIX_ERROR Bitrix24 rejected the request. See error.message for the reason and error.b24Code for the original code.
403 WRITE_BLOCKED_READONLY_KEY Writes are blocked: the key is read-only.
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

A misspelled field may not be saved. An unknown name 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