---
title: "Record stock movements"
method: POST
path: "/v1/locations/{locationId}/stock-movements"
tags: ["Stock movements"]
---

# Record stock movements

`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

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.

## Path parameters

- `locationId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- StockDocument: Stock changes that belong together, such as the rows of a delivery note or what one treatment used. Every line is applied, or none.
  - `comment` string: A note, at most 500 characters. Stored on every movement.
  - `externalReference` string: 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.
  - `lines` StockMovementLine[], required: 1 to 100 lines, applied in order.
    - `colourBarItemId` string: The colour bar item, in place of `productId`. Its `quantity` is in whole packs.
    - `movementId` string: For a `correction`: the withdrawal to undo.
    - `productId` string: The product. A `delivery` or `withdrawal` line names a product or a colour bar item, never both.
    - `quantity` integer: How many, as a whole number greater than 0. Required for all types but `correction`.
    - `reason` string: For a `withdrawal`: why, as one lower-case word such as `consumption` or `damaged`. The list is open.
    - `type` string, required: `delivery`: goods received. `withdrawal`: stock taken out. `correction`: undoes the withdrawal in `movementId`.
    - `unitCost` string: For a `delivery`: what one cost, VAT excluded, as a decimal string with at most four decimals. 0 when left out.
  - `staffId` string: The staff member who did it. Shown as who made the movements.

## Response `200`

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

- StockDocumentResult
  - `data` StockMovement[], required: The movements made, in the order of the lines.
    - `balanceAfter` integer, required: The balance after this movement.
    - `colourBarItemId` string: The colour bar item whose balance changed, in packs. Left out when the movement is a product's.
    - `colourBarMixId` string: The colour bar mix that made the movement, by finishing a pack or by being undone. Such a movement is not corrected on its own: the mix is undone.
    - `comment` string
    - `correctedByMovementId` string: On a movement that has been corrected: its correction.
    - `correctsMovementId` string: On a correction: the movement it undoes.
    - `createdAt` string, date-time, required
    - `externalReference` string: The caller's own reference for what the movement belongs to.
    - `id` string, required: Movement id.
    - `listValue` string: On a withdrawal: what was taken, at the list price then of the article in a supplier's catalogue that it is linked to, VAT excluded, as a decimal string. Left out when there is no such list price. It is kept as it was: a later change of the list price does not change it.
    - `productId` string: The product whose balance changed. Left out when the movement is a colour bar item's.
    - `quantity` integer, required: The change applied to the balance: negative when stock left.
    - `reason` string: Why stock was taken out: a lower-case word such as `consumption` or `damaged`. The list is open, so accept a value you do not know.
    - `residue` integer: On a withdrawal made by a colour bar mix: the grams that were never taken from the pack it finished.
    - `shortfall` integer, required: How much of what was asked for was not in stock; the balance never goes below 0. A sale of 3 with 1 in stock has `quantity` -1 and `shortfall` 2. 0 when everything was in stock.
    - `staffId` string: Who made it, when a staff member did: look the name up in the staff list. Left out for a movement made without one, such as by an administrator in Cliento.
    - `type` string, required: `sale` and `refund`: at the point of sale. `delivery`: goods received, or the adjustment made when a delivery is changed afterwards. `withdrawal`: taken out by hand. `correction`: undoes the movement in `correctsMovementId`. `stocktake`: the difference found by a count. `opening_balance`: the balance when movements began to be recorded for the product. More values may be added.

## Other responses

- `201`: The movements were made.
- `default`: Any failure. See the Errors section.

---

[API](https://skmtc.dev/cliento/apis/cliento-api.md) · [All operations](https://skmtc.dev/cliento/apis/cliento-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliento/apis/cliento-api/revisions/29ca811bc061?raw)