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
Parameterlimit (query) Typenumber Default50 DescriptionNumber of records, from 1 to 5000. A non-numeric value is replaced with 50
Parameteroffset (query) Typenumber Default0 DescriptionSkip N records. The value does not have to be a multiple of the page size: ?offset=4 starts the output at the fifth record
Parameterselect (query) Typestring Default— DescriptionComma-separated field selection: ?select=id,code. Field names come from GET /v1/catalog-measures/fields
Parametersort (query) Typestring Defaultid DescriptionShorthand sorting: ?sort=-code. A minus sign indicates descending order. Without the parameter, records are sorted by id ascending
Parameterorder (query) Typeobject Default— DescriptionSorting in object form: ?order[code]=desc
Parameterfilter (query) Typeobject Default— DescriptionFiltering by the fields of GET /v1/catalog-measures/fields.
Filtering syntax. Example: ?filter[code]=796
ParameterwithTotal (query) Typestring Default— DescriptionWhether 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of units of measure
Fielddata[].id Typenumber DescriptionUnit identifier. It is passed in the product's measure field
Fielddata[].code Typenumber DescriptionUnit code in the Russian National Classifier of Units of Measurement (OKEI)
Fielddata[].measureTitle Typestring | null DescriptionUnit of measure name
Fielddata[].symbol Typestring | null DescriptionShort symbol
Fielddata[].symbolIntl Typestring | null DescriptionInternational symbol
Fielddata[].symbolLetterIntl Typestring | null DescriptionInternational letter symbol
Fielddata[].isDefault Typestring DescriptionDefault unit: Y or N
Fieldmeta.total Typenumber DescriptionNumber of records matching the filter. Always returned, including with withTotal=false
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond limit
Fieldmeta.warnings Typearray DescriptionRequest 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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionA filter on a field that is not in the unit of measure schema. The message lists the available fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field that is not in the schema. The message lists the available fields
HTTP400 CodeINVALID_FILTER DescriptionTwo filter forms are mixed in one request — filter[field]=… and filter={...}. Pass all conditions in one form
HTTP400 CodeINVALID_FILTER DescriptionThe 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
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionUnknown operator in a filter condition, for example $foo. The message lists the supported operators
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionA 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded: 300 per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the interval given in the Retry-After header

For the full list of common API errors, see 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