# Inventory document items

Product lines of [inventory documents](./catalog-documents.md): which product moves, in what quantity, at what purchase price, and between which warehouses. One document can have several items. Items can be changed until the document is conducted.

Bitrix24 API: `catalog.document.element.*`
Scope: `catalog`

## Operations

- [Create an item](./catalog-document-elements/create.md) — `POST /v1/catalog-document-elements`
- [List items](./catalog-document-elements/list.md) — `GET /v1/catalog-document-elements`
- [Get an item](./catalog-document-elements/get.md) — `GET /v1/catalog-document-elements/:id`
- [Update an item](./catalog-document-elements/update.md) — `PATCH /v1/catalog-document-elements/:id`
- [Delete an item](./catalog-document-elements/delete.md) — `DELETE /v1/catalog-document-elements/:id`
- [Search items](./catalog-document-elements/search.md) — `POST /v1/catalog-document-elements/search`
- [Item fields](./catalog-document-elements/fields.md) — `GET /v1/catalog-document-elements/fields`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Item ID (read-only) |
| `docId` | number | Document — an ID from [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list). Set only on create |
| `elementId` | number | Product — an ID from [`GET /v1/catalog-products`](/docs/entities/catalog-products/list). Set only on create |
| `amount` | number | Product quantity |
| `purchasingPrice` | number | Purchase price per unit |
| `storeFrom` | number | Source warehouse — an ID from [`GET /v1/warehouses`](/docs/entities/warehouses/list) |
| `storeTo` | number | Destination warehouse — an ID from [`GET /v1/warehouses`](/docs/entities/warehouses/list) |

Full field list — [`GET /v1/catalog-document-elements/fields`](./catalog-document-elements/fields.md).

## Before you start

1. **The request body is flat.** On create and update, pass fields directly at the JSON root: `{"docId": 42, "elementId": 6595, "amount": 3}`. No `fields` wrapper is needed.
2. **`docId` and `elementId` are required on create.** Neither field can be changed after creation: an update request that includes them returns `400 READONLY_FIELD`. To move a product to another document or replace the product, delete the item and create a new one.
3. **Warehouses depend on the document type.** A goods receipt (`A`), a stock adjustment (`S`) and a return (`R`) need the destination warehouse `storeTo`, a write-off (`D`) needs the source warehouse `storeFrom`, and a transfer (`M`) needs both. An item with unsuitable warehouses is created without an error, but conducting the document is rejected with `422 BITRIX_ERROR` and the name of the product that has no warehouse set.
4. **Items of a conducted document cannot be changed.** Adding an item to a conducted document, updating its items, and deleting them are rejected with `422 BITRIX_ERROR`. First, [cancel conducting the document](/docs/entities/catalog-documents/cancel).
5. **Items are deleted together with the document.** You do not need to delete them separately before [deleting the document](/docs/entities/catalog-documents/delete). After deletion, requesting an item by its `id` returns `404 ENTITY_NOT_FOUND`.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Inventory documents | [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list) | The document the item belongs to — the `docId` value. The document type determines which warehouses the item needs. |
| Catalog products | [`GET /v1/catalog-products`](/docs/entities/catalog-products/list) | Products for the `elementId` field. |
| Warehouses | [`GET /v1/warehouses`](/docs/entities/warehouses/list) | Warehouses for the `storeFrom` and `storeTo` fields. Stock after conducting — [`GET /v1/warehouses/:id/stock`](/docs/entities/warehouses/stock). |

## Typical scenario

Filling a document with products before conducting it:

1. Find the document: [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list) — take `id` and `docType`.
2. View its items: [`GET /v1/catalog-document-elements?filter[docId]=:id`](./catalog-document-elements/list.md).
3. Add a product: [`POST /v1/catalog-document-elements`](./catalog-document-elements/create.md) with `docId`, `elementId`, `amount`, and the warehouses the document type requires.
4. Correct the quantity or price: [`PATCH /v1/catalog-document-elements/:id`](./catalog-document-elements/update.md).
5. Conduct the document: [`POST /v1/catalog-documents/:id/conduct`](/docs/entities/catalog-documents/conduct).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| 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

- [Inventory documents](./catalog-documents.md)
- [Warehouses](./warehouses.md)
- [Catalog products](./catalog-products.md)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)