# Catalog measures

Reference list of units of measure in the product catalog: pieces, kilograms, liters, and other units in which product quantity is specified. The unit identifier is passed in a product's `measure` field.

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

## Operations

- [Create a unit of measure](./catalog-measures/create.md) — `POST /v1/catalog-measures`
- [List units of measure](./catalog-measures/list.md) — `GET /v1/catalog-measures`
- [Get a unit of measure](./catalog-measures/get.md) — `GET /v1/catalog-measures/:id`
- [Update a unit of measure](./catalog-measures/update.md) — `PATCH /v1/catalog-measures/:id`
- [Delete a unit of measure](./catalog-measures/delete.md) — `DELETE /v1/catalog-measures/:id`
- [Search units of measure](./catalog-measures/search.md) — `POST /v1/catalog-measures/search`
- [Unit of measure fields](./catalog-measures/fields.md) — `GET /v1/catalog-measures/fields`

## Key fields

| Field | Description |
|------|---------|
| `id` | Measure identifier. Pass it in a product's `measure` field |
| `code` | Unit code from the Russian National Classifier of Units of Measurement (OKEI), an integer. Unique within the Bitrix24 account |
| `measureTitle` | Measure name |
| `symbol` | Short symbol |
| `symbolIntl` | International symbol |
| `symbolLetterIntl` | International letter symbol |
| `isDefault` | Default measure: `Y` or `N` |

Full field list: [`GET /v1/catalog-measures/fields`](./catalog-measures/fields.md).

## What to know before you start

1. **The request body is flat.** On create and update, fields go in the JSON root: `{"code": 9001, "measureTitle": "Package"}`. No `fields` wrapper is needed.
2. **Creation requires two fields:** `code` and `measureTitle`. The code is unique within the Bitrix24 account: reusing an existing `code` returns `422 BITRIX_ERROR` with the message `Duplicate entry for key [code]`.
3. **The name can be empty.** For some measures `measureTitle` and `symbol` come back as `null`, and the symbol is filled only in `symbolIntl` and `symbolLetterIntl`. On the tested Bitrix24 account this applies to five standard measures: meter, liter, gram, kilogram, and piece. For display, use `measureTitle`, and fall back to `symbolIntl` when it is `null`.
4. **There is one default measure.** The value `isDefault: "Y"` is set on exactly one measure in the Bitrix24 account.
5. **Values are validated before the write.** A fractional `code` or an `isDefault` other than `Y` or `N` is rejected with `400 INVALID_PARAMS`, and no record is created or changed.
6. **Batch writes do not accept `null`.** A field with the value `null` in a batch is rejected: `POST /v1/catalog-measures/batch` returns `400 BATCH_ITEM_VALIDATION`, and a call inside `POST /v1/batch` is rejected with the code `INVALID_PARAMS` in `data.errors`. To clear `symbol`, `symbolIntl`, or `symbolLetterIntl`, send a single [`PATCH /v1/catalog-measures/:id`](./catalog-measures/update.md).

## Typical scenario

Adding a product in your own unit of measure:

1. Check whether the measure exists: [`GET /v1/catalog-measures?filter[code]=778`](./catalog-measures/list.md).
2. If it does not, create it: [`POST /v1/catalog-measures`](./catalog-measures/create.md) with `code` and `measureTitle`, and take `id` from the response.
3. Pass this `id` in the `measure` field when creating the product: [`POST /v1/catalog-products`](/docs/entities/catalog-products/create).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| Single-entity batch | [`POST /v1/catalog-measures/batch`](/docs/entity-api) — write actions `create`, `update`, `delete` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Catalog products](/docs/entities/catalog-products)
- [CRM products](/docs/entities/products)
- [Catalog VAT rates](/docs/entities/catalog-vat-rates)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)