Stock movements

Record stock movements

Records a document of stock changes: a delivery note, products taken from the shelf for the location's own use. Every line is applied, or none: a line that takes out more than is in stock gets the whole document refused with insufficient_stock. Answers 201 with the movements made, and 200 with the movements made the first time when externalReference was used before. A correction line needs the scope stock:correct as well, and a delivery line the scope stock:cost, since it sets what the goods cost.

post/v1/locations/{locationId}/stock-movements

Request

  • Base URL: https://api.cliento.com
  • URL: https://api.cliento.com/v1/locations/{locationId}/stock-movements
  • Auth: HTTP bearer

Path parameters

locationIdstring required

Headers

Idempotency-Keystring

A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely.

Request body

commentstring

A note, at most 500 characters. Stored on every movement.

externalReferencestring

Your own reference for the document, such as a delivery note number, 1 to 100 characters. A document whose reference has been used at the location changes nothing and is answered with the movements made the first time, so it is safe to send again at any time.

staffIdstring

The staff member who did it. Shown as who made the movements.

Example request

{
  "comment": "Colour for Anna, 14:00",
  "externalReference": "DN-2026-10412",
  "lines": [
    {
      "colourBarItemId": "cbi_3Vn8Kq5TzL1xWc7PdM2RbJ",
      "movementId": "mov_9Bd2fHk4Mn7Pq1Sv6XzCtA",
      "productId": "prd_5Tg8mPq1Xc7Jd2Ls9WbNrK",
      "quantity": 2,
      "reason": "consumption",
      "type": "withdrawal",
      "unitCost": "62.4500"
    }
  ],
  "staffId": "stf_7Qm2xLd9Kc4Vb1Ts8HpWzE"
}

Response

The externalReference was used before. Nothing in this request was applied; the movements made then are returned.

Example response

{
  "data": [
    {
      "balanceAfter": 505,
      "colourBarItemId": "cbi_3Vn8Kq5TzL1xWc7PdM2RbJ",
      "colourBarMixId": "cbm_8Wq3Nd6HtY1mKx4LcP9RvB",
      "comment": "Colour for Anna, 14:00",
      "correctedByMovementId": "mov_6Wr3tYu8Io1Pa4Sd7FgHjK",
      "correctsMovementId": "mov_9Bd2fHk4Mn7Pq1Sv6XzCtA",
      "createdAt": "2026-10-11T09:24:31.512Z",
      "externalReference": "visit-88213",
      "id": "mov_3Lp6vRt9Yx2Kc5Ng8QwEzH",
      "listValue": "304.00",
      "productId": "prd_5Tg8mPq1Xc7Jd2Ls9WbNrK",
      "quantity": -2,
      "reason": "consumption",
      "residue": 3,
      "staffId": "stf_7Qm2xLd9Kc4Vb1Ts8HpWzE",
      "type": "withdrawal"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.