## Book a stock correction (tenant:stock:write)

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

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

Books a signed correction movement. The reason is required (`422` without). Each request books a new movement.

### Parameters

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

### Request body

`application/json` (required)

- `quantity` (number, required): Signed quantity to add to the stock.
- `reason` (string, required): Required.
- `warehouseId` (string): Empty or the default warehouse.

Example:

```json
{
  "quantity": -2,
  "reason": "Bruch im Lager"
}
```

### Responses

- **201** The booked movement (`application/json`)
- **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-18T14:20:00Z",
  "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d03",
  "kind": "correction",
  "quantity": -2,
  "reason": "Bruch im Lager",
  "serials": [],
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/stock/string/corrections' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"quantity":-2,"reason":"Bruch im Lager"}'
```
