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
success boolean Always true on success.
data.fields object Metadata map. Each key is a field name and its value describes that field.
data.batch array Write actions supported through POST /v1/catalog-vat-rates/batch: create, update, delete.
meta.warnings array If 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
id number yes VAT rate identifier. List: GET /v1/catalog-vat-rates. Pass it as the product's vatId.
name string VAT rate name. Required on creation.
rate number | null VAT percentage. Required on creation. Writes do not accept null; existing rates may return null.
active string Rate status: Y — active, N — inactive.
sort number Sort order, an integer of at least 1.
timestampX datetime yes Modification 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
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

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