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

List units of measure

GET /v1/catalog-measures

Returns the list of commercial catalog units of measure.

Parameters

Parameter Type Default Description
limit (query) number 50 Number of records, from 1 to 5000. A non-numeric value is replaced with 50
offset (query) number 0 Skip N records. The value does not have to be a multiple of the page size: ?offset=4 starts the output at the fifth record
select (query) string — Comma-separated field selection: ?select=id,code. Field names come from GET /v1/catalog-measures/fields
sort (query) string id Sorting in short syntax: ?sort=-code, a minus means descending. Without the parameter, records are sorted by id ascending
order (query) object — Sorting in object form: ?order[code]=desc
filter (query) object — Filtering by the fields of GET /v1/catalog-measures/fields.
Filtering syntax. Example: ?filter[code]=796
withTotal (query) string — Whether to return the record count: true or false. The parameter is accepted but does not affect the unit of measure output: meta.total is always returned. Paging and counts

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-measures?sort=-code&limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-measures?sort=-code&limit=3" \
  -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-measures?sort=-code&limit=3', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} units of measure`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-measures?sort=-code&limit=3', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of units of measure
data[].id number Unit identifier. It is passed in the product's measure field
data[].code number Unit code in the Russian National Classifier of Units of Measurement (OKEI)
data[].measureTitle string | null Unit of measure name
data[].symbol string | null Short symbol
data[].symbolIntl string | null International symbol
data[].symbolLetterIntl string | null International letter symbol
data[].isDefault string Default unit: Y or N
meta.total number Number of records matching the filter. Always returned, including with withTotal=false
meta.hasMore boolean Whether more records exist beyond limit
meta.warnings array Request parsing warnings. Returned when select contains a name outside the schema — code UNKNOWN_SELECT_FIELD, with the field name in field. With limit=0 — code LIMIT_ZERO_IGNORED: the value is not applied and the default page is returned

Response example

Request ?sort=-code&limit=3:

JSON 
{
  "success": true,
  "data": [
    {
      "code": 796,
      "id": 9,
      "isDefault": "Y",
      "measureTitle": null,
      "symbol": null,
      "symbolIntl": "pc. 1",
      "symbolLetterIntl": "PCE. NMB"
    },
    {
      "code": 166,
      "id": 7,
      "isDefault": "N",
      "measureTitle": null,
      "symbol": null,
      "symbolIntl": "kg",
      "symbolLetterIntl": "KGM"
    },
    {
      "code": 163,
      "id": 5,
      "isDefault": "N",
      "measureTitle": null,
      "symbol": null,
      "symbolIntl": "g",
      "symbolLetterIntl": "GRM"
    }
  ],
  "meta": {
    "total": 6,
    "hasMore": true
  }
}

Error response example

400 — a filter on a field that is not in the schema:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'nope' for entity 'catalog-measures'. Available: id, code, measureTitle, symbol, symbolIntl, symbolLetterIntl, isDefault"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD A filter on a field that is not in the unit of measure schema. The message lists the available fields
400 UNKNOWN_SORT_FIELD Sorting by a field that is not in the schema. The message lists the available fields
400 INVALID_FILTER Two filter forms are mixed in one request — filter[field]=… and filter={...}. Pass all conditions in one form
400 INVALID_FILTER The filter value is neither bracket notation nor a JSON object, for example ?filter=notjson. Such a filter cannot be applied, so the request is rejected
400 INVALID_FILTER_OPERATOR Unknown operator in a filter condition, for example $foo. The message lists the supported operators
400 INVALID_FILTER_OPERATOR A logical key $or, $and or $not in the filter. An OR condition on one field is expressed with the $in operator, across different fields — with parallel requests through POST /v1/batch
403 SCOPE_DENIED The API key does not have the catalog scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY The X-Api-Key header is missing
429 RATE_LIMITED Request limit exceeded: 300 per minute per Bitrix24 account, and all API keys of the account share one limit. The exact value is in the x-ratelimit-limit header (the ceiling is divided across replicas). Retry after the interval given in the Retry-After header

Full list of common API errors — Errors.

Known specifics

An unknown name in select does not reject the request. Unlike filter and sort, the response comes with code 200: the records keep only the schema fields, and meta.warnings gets an UNKNOWN_SELECT_FIELD warning. Check meta.warnings so that a typo in a field name does not go unnoticed.

See also