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

Update a VAT rate

PATCH /v1/catalog-vat-rates/:id

Partially updates a VAT rate in the product catalog. Send only the fields to change in a flat body, without a fields wrapper.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionVAT rate identifier, a non-negative integer. List: GET /v1/catalog-vat-rates.

Request body fields

Field Type Required Description
Fieldname Typestring Requiredno DescriptionVAT rate name.
Fieldrate Typenumber Requiredno 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.
Fieldid Typenumber Requiredno DescriptionRO. Set only in the path. Passing it in the body returns 400 READONLY_FIELD.
FieldtimestampX Typestring Requiredno DescriptionRO. The modification time is set by Bitrix24. Passing it in the body returns 400 READONLY_FIELD.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/catalog-vat-rates/25" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs VAT updated 2026-10-08"
}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/catalog-vat-rates/25" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs VAT updated 2026-10-08"
}'

JavaScript — personal key

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

const { success, data } = await res.json()
console.log(data)

JavaScript — OAuth application

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

const { success, data } = await res.json()
console.log(data)

Response fields

On success, returns 200 and the complete updated 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 updated 2026-10-08",
    "rate": 7.5,
    "sort": 900,
    "timestampX": "2026-10-08T18:50:04.000Z"
  }
}

Error response example

422 — rate is null. The rate is not changed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: rate",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo VAT rate exists with this id, including after deletion.
HTTP400 CodeINVALID_PARAMS Descriptionid is not a non-negative integer, for example abc.
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe body is empty or is not a JSON object. Provide at least one 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 Descriptionrate: null is rejected with Required fields: rate. For other errors returned by Bitrix24, see error.message and error.b24Code.
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

A single PATCH does not require repeating name and rate. If a field is omitted, Vibecode supplies the rate's current value before updating it. An explicit null is not replaced. If an existing rate has rate: null, provide a numeric rate; otherwise Bitrix24 may reject a change to another field.

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