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
filter (query) object — Filter 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
select (query) string — Comma-separated response fields: ?select=id,elementId,amount. The id field is always returned. Names come from GET /v1/catalog-document-elements/fields
order (query) object — Sorting: ?order[amount]=desc. Short form — ?sort=-amount, a minus means descending. Fields are the same as in the filter
limit (query) number 50 Number of records, up to 5000
offset (query) number 0 Number of records to skip from the start of the result set
withTotal (query) string — true 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
success boolean Always true on success
data array Array of items
data[].id number Item ID
data[].docId number Inventory document ID. Document — GET /v1/catalog-documents/:id
data[].elementId number Product ID. Product — GET /v1/catalog-products/:id
data[].amount number | null Product quantity, null — not set
data[].purchasingPrice number | null Purchase price per unit, null — not set
data[].storeFrom number | null Source warehouse, null — no warehouse set. Warehouses — GET /v1/warehouses
data[].storeTo number | null Destination warehouse, null — no warehouse set. Warehouses — GET /v1/warehouses
meta.total number Total number of items matching the filter. Optional: absent when withTotal=false
meta.hasMore boolean Whether there are more items beyond limit
meta.warnings array Request 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
400 UNKNOWN_FILTER_FIELD Filter by a field that is not in the schema. The message lists the allowed fields
400 UNKNOWN_SORT_FIELD Sorting by a field that is not in the schema. The message lists the allowed fields
400 INVALID_FILTER The 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
400 INVALID_FILTER_OPERATOR The filter contains an unsupported operator. The message lists the supported ones
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The API key passed was not found
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key does not have the catalog scope
429 RATE_LIMITED Rate 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