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

Create an inventory document

POST /v1/catalog-documents

Creates an inventory document — the header of a receipt, stock adjustment, transfer, return or write-off.

Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field	Type	Required	Description
`docType`	string	yes	Document type: `A` — receipt, `S` — stock adjustment, `M` — transfer, `R` — return, `D` — write-off. Cannot be changed after creation. More on the types — Inventory documents
`currency`	string	yes	Document currency. Cannot be changed after creation. List: `GET /v1/currencies`
`responsibleId`	number	yes	Responsible employee. List: `GET /v1/users`
`title`	string	no	Document title
`docNumber`	string	no	Document number
`commentary`	string	no	Comment
`dateDocument`	datetime	no	Document date
`total`	number	no	Document total. Not calculated from the document items: after conducting, the field holds the passed value or `null`
`siteId`	string	no	Bitrix24 site ID. If omitted at creation, `s1` is used
`createdBy`	number	no	Employee who created the document. Cannot be changed after creation. List: `GET /v1/users`
`modifiedBy`	number	no	Employee who last modified the document. List: `GET /v1/users`
`statusBy`	number	no	Employee who last changed the conducting status. List: `GET /v1/users`
`dateModify`	datetime	no	Last modification date

Full field list — GET /v1/catalog-documents/fields.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-documents" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docType": "S",
    "currency": "USD",
    "responsibleId": 1,
    "title": "Stock correction — documentation check"
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-documents" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docType": "S",
    "currency": "USD",
    "responsibleId": 1,
    "title": "Stock correction — documentation check"
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    docType: 'S',
    currency: 'USD',
    responsibleId: 1,
    title: 'Stock correction — documentation check',
  }),
})

const { success, data } = await res.json()
console.log('Document ID:', data.id)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    docType: 'S',
    currency: 'USD',
    responsibleId: 1,
    title: 'Stock correction — documentation check',
  }),
})

const { success, data } = await res.json()

Response fields

HTTP status 201 Created.

Field	Type	Description
`success`	boolean	`true` on successful creation
`data`	object	The created document. All fields — Inventory document fields
`data.id`	number	ID of the created document
`data.status`	string	Conducting status. A new document always has `N` — not conducted
`data.dateCreate`	datetime	Creation date, ISO 8601 in UTC
`data.dateStatus`	datetime	Date of the last status change. For a new document it equals `dateCreate`
`data.dateModify`	datetime	Last modification date
`meta.warnings`	array	Returned only if the body contains a field that is not among the document fields. Each item has `code: "UNRECOGNIZED_WRITE_FIELD"`, `field` with the field name, and `message`. On a route that wraps the field map itself, an object under `fields` is rejected with `400 NESTED_FIELDS_ENVELOPE` when the schema does not declare `fields`; pass fields flat at the JSON root.

Response example

JSON

{
  "success": true,
  "data": {
    "commentary": null,
    "createdBy": 1,
    "currency": "USD",
    "dateCreate": "2026-10-12T13:20:16.000Z",
    "dateDocument": null,
    "dateModify": "2026-10-12T13:20:16.000Z",
    "dateStatus": "2026-10-12T13:20:16.000Z",
    "docNumber": null,
    "docType": "S",
    "id": 299,
    "modifiedBy": 1,
    "responsibleId": 1,
    "siteId": "s1",
    "status": "N",
    "statusBy": null,
    "title": "Stock correction — documentation check",
    "total": null
  }
}

Error response example

400 — a required field is missing: