# Catalog VAT rates

Reference data for product catalog VAT rates: names, percentages, status, and sort order. Pass a rate's identifier as the product's `vatId`.

Bitrix24 API: `catalog.vat.*`
Scope: `catalog`

## Operations

- [Create a VAT rate](./catalog-vat-rates/create.md) — `POST /v1/catalog-vat-rates`
- [List VAT rates](./catalog-vat-rates/list.md) — `GET /v1/catalog-vat-rates`
- [Get a VAT rate](./catalog-vat-rates/get.md) — `GET /v1/catalog-vat-rates/:id`
- [Update a VAT rate](./catalog-vat-rates/update.md) — `PATCH /v1/catalog-vat-rates/:id`
- [Delete a VAT rate](./catalog-vat-rates/delete.md) — `DELETE /v1/catalog-vat-rates/:id`
- [Search VAT rates](./catalog-vat-rates/search.md) — `POST /v1/catalog-vat-rates/search`
- [VAT rate fields](./catalog-vat-rates/fields.md) — `GET /v1/catalog-vat-rates/fields`

## Key fields

| Field | Description |
|------|------|
| `id` | VAT rate identifier. List: [`GET /v1/catalog-vat-rates`](/docs/entities/catalog-vat-rates/list). Pass it as the product's `vatId`. |
| `name` | VAT rate name. |
| `rate` | VAT percentage. For an existing "No VAT" rate, this field may be `null`. |
| `active` | Rate status: `Y` — active, `N` — inactive. |
| `sort` | Sort order. |
| `timestampX` | Modification date and time in ISO 8601 format. Set by Bitrix24. |

## Before you start

1. **The request body is flat.** On creation and update, send fields at the JSON root without a `fields` wrapper.
2. **Creation requires `name` and `rate`.** The percentage may be fractional or `0`. Creating a rate with `rate: null` returns `400 MISSING_REQUIRED_FIELDS`.
3. **A No VAT rate may have `rate: null`.** This occurs in existing records and differs from a numeric rate of `0`. PATCH with `rate: null` returns `422 BITRIX_ERROR` with `Required fields: rate`.
4. **A single PATCH accepts only the fields to change.** Omitted `name` and `rate` are supplied from the current record. In a batch update, provide both fields in every item.
5. **Values are validated before writing.** `active` accepts `Y` or `N`; `sort` must be an integer of at least `1`. `id` and `timestampX` are read-only. Sending them in the body returns `400 READONLY_FIELD`.
6. **Before deleting a rate, check products that use it.** Find them by `vatId` in the [catalog product list](/docs/entities/catalog-products/list). To retain a record whose current `rate` is numeric, deactivate it with `active: "N"`. For an existing "No VAT" rate with `rate: null`, this PATCH is rejected with `422 BITRIX_ERROR` and `Required fields: rate`. The record remains active. An `active`-only PATCH cannot deactivate it while `rate` remains `null`.

## Typical workflow

Set up a rate for a product:

1. Find a rate with [`GET /v1/catalog-vat-rates?filter[active]=Y`](./catalog-vat-rates/list.md) or [search](./catalog-vat-rates/search.md).
2. If the rate does not exist, [create it](./catalog-vat-rates/create.md).
3. Pass the returned `id` as `vatId` when [creating a catalog product](/docs/entities/catalog-products/create).
4. To change the name or percentage, [PATCH the rate](./catalog-vat-rates/update.md), then [read it](./catalog-vat-rates/get.md) to verify the result.

## Limits

List and search accept `limit` from 1 to 5000, with a default of `50`. Use `offset` and `meta.hasMore` to paginate. Vibecode fetches additional pages automatically when `limit > 50`.

Batch writes are available through `POST /v1/catalog-vat-rates/batch` and the universal `POST /v1/batch`. See [Batch calls](/docs/batch) for the procedure. Aggregation is not available for this reference entity.

## See also

- [VAT rate fields](/docs/entities/catalog-vat-rates/fields)
- [Catalog products](/docs/entities/catalog-products)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)