# Inventory documents

Inventory management documents: goods receipt, stock adjustment, transfer between warehouses, return and write-off. A document is a header with a type, a currency and a responsible user. Products and warehouses are set by its [items](./catalog-document-elements.md). Warehouse stock changes when the document is conducted and reverts when conducting is canceled.

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

## Operations

- [Create an inventory document](./catalog-documents/create.md) — `POST /v1/catalog-documents`
- [List inventory documents](./catalog-documents/list.md) — `GET /v1/catalog-documents`
- [Get an inventory document](./catalog-documents/get.md) — `GET /v1/catalog-documents/:id`
- [Update an inventory document](./catalog-documents/update.md) — `PATCH /v1/catalog-documents/:id`
- [Delete an inventory document](./catalog-documents/delete.md) — `DELETE /v1/catalog-documents/:id`
- [Search inventory documents](./catalog-documents/search.md) — `POST /v1/catalog-documents/search`
- [Inventory document fields](./catalog-documents/fields.md) — `GET /v1/catalog-documents/fields`
- [Conduct a document](./catalog-documents/conduct.md) — `POST /v1/catalog-documents/:id/conduct`
- [Cancel conducting](./catalog-documents/cancel.md) — `POST /v1/catalog-documents/:id/cancel`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Document ID (read-only) |
| `docType` | string | Document type: `A` — goods receipt, `S` — stock adjustment, `M` — transfer, `R` — return, `D` — write-off. Set only on creation |
| `currency` | string | Document currency. Set only on creation. Currency list — [`GET /v1/currencies`](/docs/entities/currencies/list) |
| `responsibleId` | number | Responsible user — an ID from [`GET /v1/users`](/docs/entities/users/list) |
| `status` | string | Conducting status: `Y` — conducted, `N` — not conducted. Read-only, changed by the [conduct](./catalog-documents/conduct.md) and [cancel conducting](./catalog-documents/cancel.md) actions |
| `title` | string | Document title |
| `docNumber` | string | Document number |
| `dateDocument` | datetime | Document date |
| `dateCreate` | datetime | Creation date (read-only) |

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

## Before you start

1. **The request body is flat.** On create and update, pass fields at the JSON root: `{"docType": "S", "currency": "USD", "responsibleId": 1}`. No `fields` wrapper is needed.
2. **Three fields are required for creation:** `docType`, `currency` and `responsibleId`. `docType` and `currency` cannot change after creation: an update request with them returns `400 READONLY_FIELD`.
3. **Five document types are supported:** `A`, `S`, `M`, `R`, `D`. Other type codes are rejected with `422 BITRIX_ERROR`.
4. **A document has two states.** A new document is not conducted (`status: "N"`): you can change and delete the document and add and edit its items. After [conducting](./catalog-documents/conduct.md) (`status: "Y"`), changing or deleting the document and its items is rejected with `422 BITRIX_ERROR`. To edit the document again, [cancel conducting](./catalog-documents/cancel.md).
5. **Warehouses are checked on conducting.** An item with warehouses that do not fit the document type is created without an error, but conducting the document is rejected with `422 BITRIX_ERROR`. Which warehouses each type needs — [Inventory document items](./catalog-document-elements.md).
6. **A goods receipt (`A`) is conducted only with a supplier specified.** The document fields have no supplier, so conducting a goods receipt created through the API is rejected with `422 BITRIX_ERROR` "Supplier is not specified". A stock adjustment (`S`) does not require a supplier.
7. **Deleting a document deletes its items.** After `DELETE /v1/catalog-documents/:id`, the items of this document no longer exist.
8. **Dates are returned in ISO 8601 UTC:** `2026-10-12T13:20:16.000Z`.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Inventory document items | [`GET /v1/catalog-document-elements?filter[docId]=:id`](/docs/entities/catalog-document-elements/list) | Products of the document: quantity, purchase price, source and destination warehouses. |
| Warehouses | [`GET /v1/warehouses`](/docs/entities/warehouses/list) | Warehouses for the `storeFrom` and `storeTo` item fields. Stock after conducting — [`GET /v1/warehouses/:id/stock`](/docs/entities/warehouses/stock). |
| Catalog products | [`GET /v1/catalog-products`](/docs/entities/catalog-products/list) | Products for the `elementId` item field. |

## Typical scenario

Adding products to a warehouse with a stock adjustment:

1. Pick a warehouse: [`GET /v1/warehouses`](/docs/entities/warehouses/list) — take the warehouse `id`.
2. Create a stock adjustment document: [`POST /v1/catalog-documents`](./catalog-documents/create.md) with `docType: "S"`, `currency` and `responsibleId`.
3. Add products: [`POST /v1/catalog-document-elements`](/docs/entities/catalog-document-elements/create) — one item per product with `docId`, `elementId`, `amount` and `storeTo`.
4. Conduct the document: [`POST /v1/catalog-documents/:id/conduct`](./catalog-documents/conduct.md).
5. Check the stock: [`GET /v1/warehouses/:id/stock`](/docs/entities/warehouses/stock).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` is 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 document items](./catalog-document-elements.md)
- [Warehouses](./warehouses.md)
- [Catalog products](./catalog-products.md)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)