ConnectCloud Developers

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:

{
  "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:

{
  "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

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"}'

View as Markdown · Interactive reference · OpenAPI