## 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

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

### curl — OAuth application

```bash
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`](/docs/entities/catalog-vat-rates/list). 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](/docs/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

- [Create a VAT rate](/docs/entities/catalog-vat-rates/create)
- [Update a VAT rate](/docs/entities/catalog-vat-rates/update)
- [List VAT rates](/docs/entities/catalog-vat-rates/list)
- [Get a VAT rate](/docs/entities/catalog-vat-rates/get)
- [Catalog products](/docs/entities/catalog-products)
- [Entity API](/docs/entity-api)