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

List inventory document items

GET /v1/catalog-document-elements

Returns inventory document items with filtering, sorting, and pagination.

Parameters

Parameter Type Default Description
Parameterfilter (query) Typeobject Default— DescriptionFilter by fields from GET /v1/catalog-document-elements/fields.
Filtering syntax. Example: ?filter[docId]=299 — items of one document, docId comes from GET /v1/catalog-documents
Parameterselect (query) Typestring Default— DescriptionComma-separated response fields: ?select=id,elementId,amount. The id field is always returned. Names come from GET /v1/catalog-document-elements/fields
Parameterorder (query) Typeobject Default— DescriptionSorting: ?order[amount]=desc. Short form — ?sort=-amount, a minus means descending. Fields are the same as in the filter
Parameterlimit (query) Typenumber Default50 DescriptionNumber of records, up to 5000
Parameteroffset (query) Typenumber Default0 DescriptionNumber of records to skip from the start of the result set
ParameterwithTotal (query) Typestring Default— Descriptiontrue or false. The exact value false omits meta.total, but Bitrix24 still counts the items, so this option does not make the request cheaper. Without it or with true, the existing counted behavior applies

Pagination. When limit is greater than 50, Vibecode assembles the response from several pages automatically. Request the next page with offset while meta.hasMore is true.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-document-elements?filter[docId]=299" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-document-elements?filter[docId]=299" \
  -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-document-elements?filter[docId]=299', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Items in the document: ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-document-elements?filter[docId]=299', {
  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 items
Fielddata[].id Typenumber DescriptionItem ID
Fielddata[].docId Typenumber DescriptionInventory document ID. Document — GET /v1/catalog-documents/:id
Fielddata[].elementId Typenumber DescriptionProduct ID. Product — GET /v1/catalog-products/:id
Fielddata[].amount Typenumber | null DescriptionProduct quantity, null — not set
Fielddata[].purchasingPrice Typenumber | null DescriptionPurchase price per unit, null — not set
Fielddata[].storeFrom Typenumber | null DescriptionSource warehouse, null — no warehouse set. Warehouses — GET /v1/warehouses
Fielddata[].storeTo Typenumber | null DescriptionDestination warehouse, null — no warehouse set. Warehouses — GET /v1/warehouses
Fieldmeta.total Typenumber DescriptionTotal number of items matching the filter. Optional: absent when withTotal=false
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more items beyond limit
Fieldmeta.warnings Typearray DescriptionRequest warnings, each with the fields code, message, field. Returned when select contains a name that is not in the schema — code UNKNOWN_SELECT_FIELD

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "amount": 3,
      "docId": 299,
      "elementId": 6595,
      "id": 33,
      "purchasingPrice": 11000,
      "storeFrom": null,
      "storeTo": 11
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Error response example

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

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogus' for entity 'catalog-document-elements'. Available: id, docId, elementId, amount, purchasingPrice, storeFrom, storeTo"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFilter by a field that is not in the schema. The message lists the allowed fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field that is not in the schema. The message lists the allowed fields
HTTP400 CodeINVALID_FILTER DescriptionThe filter value is not recognized: pass it in bracket notation ?filter[docId]=299 or as a JSON object ?filter={"docId":299}. Using both notations in one request is also rejected
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionThe filter contains an unsupported operator. The message lists the supported ones
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe API key passed was not found
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The effective value is in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

No filter — items of all documents. A request without filter[docId] returns items of all inventory documents of the Bitrix24 account in one list. To tell items of different documents apart, check the docId of each item.

Nonexistent document — empty list. A filter by the docId of a document that does not exist or was deleted returns 200 with an empty data, not an error. Without withTotal=false, meta.total is 0; with withTotal=false, the key is absent. To check that the document exists, use GET /v1/catalog-documents/:id.

See also