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

# List stock movements

`GET /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

Every change of a stock balance at the location, oldest first, including sales at the point of sale. The list can be followed: keep the id of the last movement you have read and pass it as `after` to get what has happened since. A movement appears in the list about ten seconds after it is made.

## Path parameters

- `locationId` string, required

## Query parameters

- `limit` integer
- `after` string
- `productId` string
- `colourBarItemId` string
- `type` string
- `externalReference` string

## Response `200`

OK

- StockMovementList
  - `data` StockMovement[], required
    - `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.
  - `nextCursor` string: Pass as `after` to fetch the next page. Absent when there is nothing more yet; to follow new movements, call again later with the id of the last movement you have read.

## Other responses

- `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)