## Book an inventory count (tenant:stock:write)

`POST /api/trade/v1/stock/{articleId}/counts`

Module: Trade · operationId: `countStock` · Tag: Stock · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets the on-hand stock to the counted quantity by booking the difference to the committed stock (a receipt that
arrives at the same time is not lost). The reason is required (`422` without). When the count equals the stock
nothing is booked and the answer is `204`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Request body

`application/json` (required)

- `counted` (number, required): The counted quantity; the stock is set to it.
- `reason` (string, required): Required.
- `warehouseId` (string): Empty or the default warehouse.

Example:

```json
{
  "counted": 12,
  "reason": "Jahresinventur"
}
```

### Responses

- **201** The booked difference (`application/json`)
- **204** The count equals the stock; nothing booked
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 201 answer:

- `actor` (object): Who booked the movement.
  - `kind` (string): `user`, `service`, `system`, `workflow` or `public`.
  - `name` (string): Display name of the actor.
  - `ref` (string): The lower-case e-mail of a person, the instance id of a workflow.
- `articleId` (string): Masterdata article.
- `createdAt` (string (date-time)): When the movement was booked.
- `id` (string (uuid)): Id of the movement.
- `kind` (string): `return`: goods a customer returned with a credit note, booked back in when it is issued. (one of `goods_receipt`, `delivery`, `correction`, `count`, `reversal`, `return`)
- `quantity` (number): Signed: receipts positive, deliveries negative.
- `reason` (string): Reason of a correction or count.
- `serials` (array of string): Serial numbers moved.
- `sourceNumber` (string): Number of the source document.
- `sourceTransactionId` (string (uuid)): The document the movement comes from (not for corrections and counts).
- `warehouseId` (string): Warehouse of the movement.

Example 201 answer:

```json
{
  "actor": {
    "kind": "user",
    "name": "David Richter",
    "ref": "david.richter@muster-it.example"
  },
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
  "createdAt": "2026-11-19T16:00:00Z",
  "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d04",
  "kind": "count",
  "quantity": 2,
  "reason": "Jahresinventur",
  "serials": [],
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/stock/string/counts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"counted":12,"reason":"Jahresinventur"}'
```
