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

VAT rate fields

GET /v1/catalog-vat-rates/fields

Returns metadata for VAT rate fields in the product catalog. Use it to check names, types, and allowed values before writing.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-vat-rates/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-vat-rates/fields" \
  -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/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-vat-rates/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata.fields Typeobject DescriptionMetadata map. Each key is a field name and its value describes that field.
Fielddata.batch Typearray DescriptionWrite actions supported through POST /v1/catalog-vat-rates/batch: create, update, delete.
Fieldmeta.warnings Typearray DescriptionIf full metadata is unavailable, contains a fields_partial warning. Static fields remain available in data.fields.

Each entry in fields contains type and readonly. When available, it also includes label, description, required, nullable, and enum. required: true on name and rate means they are required on creation. nullable: true on rate describes responses, not permission to write null. The active enum lists Y and N with label captions.

Fields of the VAT rate object:

Field Type RO Description
Fieldid Typenumber ROyes DescriptionVAT rate identifier. List: GET /v1/catalog-vat-rates. Pass it as the product's vatId.
Fieldname Typestring RO DescriptionVAT rate name. Required on creation.
Fieldrate Typenumber | null RO DescriptionVAT percentage. Required on creation. Writes do not accept null; existing rates may return null.
Fieldactive Typestring RO DescriptionRate status: Y — active, N — inactive.
Fieldsort Typenumber RO DescriptionSort order, an integer of at least 1.
FieldtimestampX Typedatetime ROyes DescriptionModification date and time in ISO 8601 format. Set by Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "ID",
        "description": "VAT rate identifier."
      },
      "name": {
        "type": "string",
        "readonly": false,
        "required": true,
        "label": "Name",
        "description": "VAT rate name."
      },
      "rate": {
        "type": "number",
        "readonly": false,
        "required": true,
        "nullable": true,
        "label": "Rate",
        "description": "VAT percentage. Existing No VAT rows may return null; Bitrix24 rejects null on create and update."
      },
      "active": {
        "type": "string",
        "readonly": false,
        "label": "Active",
        "description": "Y if active, N otherwise.",
        "enum": [
          {
            "value": "Y",
            "label": "Active"
          },
          {
            "value": "N",
            "label": "Inactive"
          }
        ]
      },
      "sort": {
        "type": "number",
        "readonly": false,
        "label": "Sort",
        "description": "Sort order."
      },
      "timestampX": {
        "type": "datetime",
        "readonly": true,
        "label": "Modified at",
        "description": "Bitrix24 sets this timestamp; submitted values are ignored."
      },
      "vat": {
        "type": "string",
        "readonly": false,
        "label": "vat"
      }
    },
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}

Error response example

401 — no API key was provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

HTTP Code Description
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

Metadata may contain an additional vat entry. In the verified response it has type: "string" and label: "vat". It is not one of the six VAT rate object fields listed above. Use the VAT rate object fields for filtering and sorting.

The readonly flag determines whether a field can be written. The timestampX description may say that submitted values are ignored. A Vibecode request with id or timestampX in the body is rejected with 400 READONLY_FIELD.

See also